Reverse engineering my e-scooter and rewriting the firmware in rust

Introduction

Last year, I bought myself an Egret GT. It’s an e-scooter that touts a range of 100km and has very large tyres which makes driving it quite comfortable. To make sure you know that it’s a high-end e-scooter, it comes with a 320x480 LCD display used as a HUD, on which the speed, driving mode, battery level and range are displayed.

Now because I have to break tinker with everything I own, I eventually decided to start figuring out how this thing worked. I can’t remember exactly why, but it was possibly due to the fact that holding the ‘down’ button on the keypad while powering the scooter would cause it to enter a firmware update mode. If you clicked a button to exit this menu, you would enter the normal ‘driving’ mode, and would be able to use the scooter without entering the PIN. While I always secure the scooter with a reasonably good lock, this still irked me a bit.

The first thing I started on was the mobile app, which allows you to unlock the scooter remotely, change a few settings, and view the battery level. I won’t bore you with the process, but what I found from skimming through the bluetooth handlers of the app was the following:

1. The scooter can perform firmware updates over bluetooth, and seemingly there exists a few different places a firmware update can go (display, controller, button panel).
2. Some metrics which are not shown in the app or on the scooter are transmitted over bluetooth, such as the time spent in each driving mode, device temperature, motor current, battery voltage, battery charging history. Details such as the total driving time, odometer, and charge history are transmitted to the manufacturer and stored attached to the scooter’s ID, this behaviour is not clearly mentioned in the app :)))))))
3. The scooter doesn’t know its Vehicle Identification Number until the app connects and sets it. If you set this using a bluetooth debug app yourself, the Egret app can be spoofed to think the scooter is a different model. I tried to spoof the VIN of the 45km/h model of the scooter to see if the speed limit was implemented with such a simple check, but this didn’t work.

Eventually I became bored at playing with the bluetooth interface and turned to the USB-C port on the display. The manufacturer states that this is just for charging phones, and after some testing with different devices I did conclude that if the data pins were connected, the display unit wouldn’t act as either a USB host or device. But I knew better, and ordered a USB-C breakout board. When this arrived, I plugged it in and probed each pin with an oscilloscope. To my surprise, two of the USB-C pins were being used as a CAN bus (which smells horribly noncompliant).

CAN Bus sniffing

To sniff this can traffic, I threw together an abomination (pictured in Figure 2) using an ESP32-C6, a SN65HVD230, and a MCP2515^0.

I put together a quick program which initialised the CAN peripherals and logged every can message. Then I plugged my CAN logger into the scooter and recorded the messages during startup:

1
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
2
CAN_FRAME:1025,false,[74, bd, 0, 0, 16, c, 0, 0]
3
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
4
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
5
CAN_FRAME:1025,false,[74, bd, 0, 0, 16, c, 0, 0]
6
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
7
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
8
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
9
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
10
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
11
CAN_FRAME:1025,false,[73, bd, 0, 0, 3, c, 0, 0]
12
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
13
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
14
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
15
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
16
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
17
CAN_FRAME:1025,false,[73, bd, 0, 0, 3, c, 0, 0]
18
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
19
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
20
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
21
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
22
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
23
CAN_FRAME:1025,false,[72, bd, 0, 0, ef, b, 0, 0]
24
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
25
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
26
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
27
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
28
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
29
CAN_FRAME:1025,false,[72, bd, 0, 0, ef, b, 0, 0]
30
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
31
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
32
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
33
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
34
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
35
CAN_FRAME:1025,false,[74, bd, 0, 0, e9, b, 0, 0]
36
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
37
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
38
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
39
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
40
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
41
CAN_FRAME:1025,false,[74, bd, 0, 0, e9, b, 0, 0]
42
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
43
CAN_FRAME:774,false,[55, 0, 0, 0, 2, 0, 0, 0]
44
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
45
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
46
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
47
CAN_FRAME:768,false,[0, 5a, 64, 5a, 64, 0, 0, 0]
48
CAN_FRAME:494,false,[60, 0, 0, 0, 0, 0, 0, 0]
49
CAN_FRAME:495,false,[4c, 44, 2e, 43, 52, 2e, 53, 38]
50
CAN_FRAME:495,false,[30, 37, 2e, 43, 2e, 32, 2e, 31]
51
CAN_FRAME:495,false,[45, 47, 2e, 32, 2e, 32, 2e, 31]
52
CAN_FRAME:495,false,[31, 0, 0, 0, 0, 0, 0, 0]
53
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
54
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
55
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
56
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
57
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
58
CAN_FRAME:768,false,[0, 5a, 64, 5a, 64, 0, 0, 0]
59
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
60
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
61
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
62
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
63
CAN_FRAME:1856,true,[4b, 0]
64
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
65
CAN_FRAME:1025,false,[74, bd, 0, 0, e4, b, 0, 0]
66
CAN_FRAME:1857,true,[4b, 0, 0, 0, 69, 99, 52, 42]
67
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
68
CAN_FRAME:1860,true,[1]
69
CAN_FRAME:1861,true,[1, 15, 57, 20, 50, 59, 54, 34]
70
CAN_FRAME:774,false,[54, 0, 0, 0, 2, 0, 0, 0]
71
CAN_FRAME:513,false,[0, 0, 0, 0, 2]
72
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, ff, 1f]
73
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
74
CAN_FRAME:768,false,[0, 5a, 64, 5a, 64, 0, 0, 0]

1
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
2
CAN_FRAME:1025,false,[74, bd, 0, 0, 16, c, 0, 0]
3
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
4
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
5
CAN_FRAME:1025,false,[74, bd, 0, 0, 16, c, 0, 0]
6
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
7
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
8
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
9
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
10
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
11
CAN_FRAME:1025,false,[73, bd, 0, 0, 3, c, 0, 0]
12
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
13
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
14
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
15
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
16
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
17
CAN_FRAME:1025,false,[73, bd, 0, 0, 3, c, 0, 0]
18
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
19
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
20
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
21
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
22
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
23
CAN_FRAME:1025,false,[72, bd, 0, 0, ef, b, 0, 0]
24
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
25
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
26
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
27
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
28
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
29
CAN_FRAME:1025,false,[72, bd, 0, 0, ef, b, 0, 0]
30
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
31
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
32
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
33
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
34
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
35
CAN_FRAME:1025,false,[74, bd, 0, 0, e9, b, 0, 0]
36
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
37
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
38
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
39
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
40
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
41
CAN_FRAME:1025,false,[74, bd, 0, 0, e9, b, 0, 0]
42
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
43
CAN_FRAME:774,false,[55, 0, 0, 0, 2, 0, 0, 0]
44
CAN_FRAME:513,false,[0, 0, 0, 0, 0]
45
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, 21, 0]
46
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
47
CAN_FRAME:768,false,[0, 5a, 64, 5a, 64, 0, 0, 0]
48
CAN_FRAME:494,false,[60, 0, 0, 0, 0, 0, 0, 0]
49
CAN_FRAME:495,false,[4c, 44, 2e, 43, 52, 2e, 53, 38]
50
CAN_FRAME:495,false,[30, 37, 2e, 43, 2e, 32, 2e, 31]
51
CAN_FRAME:495,false,[45, 47, 2e, 32, 2e, 32, 2e, 31]
52
CAN_FRAME:495,false,[31, 0, 0, 0, 0, 0, 0, 0]
53
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
54
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
55
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
56
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
57
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
58
CAN_FRAME:768,false,[0, 5a, 64, 5a, 64, 0, 0, 0]
59
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
60
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
61
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
62
CAN_FRAME:495,false,[0, 0, 0, 0, 0, 0, 0, 0]
63
CAN_FRAME:1856,true,[4b, 0]
64
CAN_FRAME:1024,false,[0, 40, 87, 4, 0, 0, 0, 0]
65
CAN_FRAME:1025,false,[74, bd, 0, 0, e4, b, 0, 0]
66
CAN_FRAME:1857,true,[4b, 0, 0, 0, 69, 99, 52, 42]
67
CAN_FRAME:1028,false,[20, 4e, 0, 0, 1, 0, b9, b]
68
CAN_FRAME:1860,true,[1]
69
CAN_FRAME:1861,true,[1, 15, 57, 20, 50, 59, 54, 34]
70
CAN_FRAME:774,false,[54, 0, 0, 0, 2, 0, 0, 0]
71
CAN_FRAME:513,false,[0, 0, 0, 0, 2]
72
CAN_FRAME:515,false,[0, 0, 0, 0, 0, 0, ff, 1f]
73
CAN_FRAME:528,false,[0, 0, 0, 0, 0, 0, 0, 0]
74
CAN_FRAME:768,false,[0, 5a, 64, 5a, 64, 0, 0, 0]

The CAN bus proved to be quite noisy, so to figure out what was going on I built a small tool using egui to show a plot of can messages against time. By plotting each can message as a dot with the y-axis as the can message ID, it becomes very easy to identify which messages are commands, responses, and periodic data.

Unfortunately at this point I still didn’t have a good idea which purpose each message had. But by sniffing the bus while running the scooter, I was able to quickly figure out which messages were used in communicating the throttle, driving mode, and motor speed:

• 0x300: Sent by the display to the controller. Contains the current driving mode (walk, eco, drive, sport), whether the headlight is on, and in walk mode contains a counter in the last nibble. Sending a message where the fourth byte is a5 instead of the usual 5a causes the controller to reset.

  An example is which decodes to:

  Driving mode	Walk (0x00_90)
  Headlight	Operating (0x64)
  Walk counter	0

• 0x306: Sent by the display to the controller. Contains the throttle position, the blinker lights, and the speed limit of the scooter. The speed limit has no effect on the standard GT controller, but on the GTS it sets the speed limit to 25, 35, or 45km/h. For some reason the throttle level is transmitted as a 9 bit unsigned integer with the MSB being the first bit of the second byte.

  An example is which decodes to:

  Throttle	511
  Left blinker	true
  Right blinker	false
  Speed limit	25km/h (0)

• 0x201: Contains motor speed, and some status flags.

  An example is which decodes to:

  Motor speed	1031
  Walk mode	false
  Headlight on	false
  Brake light on	true

In the end, I documented all of the CAN messages: here.

At this point I was now able to do some amusing stuff, like controlling the scooter’s motor remotely, but this isn’t very practical or interesting. This project kind of stalled at this point as I had no access to the firmware and therefore there was little more I could do. A few months later I noticed that it was possible to buy replacement motor controller and display units online. I couldn’t resist the opportunity, so I ordered replacements of both.

Teardowns and firmware extraction

The first component I tore down was the controller. This was particularly difficult as the rear plate was secured very tightly with crosshead screws, of which the heads of two stripped immediately, requiring me to dremel a slot. The device was also filled with some type of potting compound, but very thankfully the compound was actually quite soft and could easily be scraped away.

After removing the potting compound, I was presented with quite the gift: None of the active components had had their markings etched away, and there was a row of four pads on the back side of the board. The MCU was marked with APM32E103xCxE (a STM32F103 clone), therefore these pins are very likely the SWD port. By using OpenOCD^1 I was able to dump the flash and the RAM^2 contents shortly after boot.

With the firmware dumped I could start analysing it with Ghidra^3. I very quickly found the main CAN message handler, which allowed me to further document the purpose of each CAN message.

I also discovered that a total of three applications live on the controller MCU: A bootloader located at 0x8000000, an ‘updater’ at 0x8003000, and the main application at 0x8006200. The bootloader sets up the CAN bus and listens for a short time to see if any ‘update’ packets arrive, to see if a firmware update over the CAN bus is in progress. For some reason both the bootloader and ‘updater’ firmware contain a mechanism to update the application firmware over CAN bus, both use a different update scheme.

Another funny note is that at 0x8006000 the length of the application firmware is stored, but not as a four or eight byte unsigned integer as you’d inspect, but instead as an ascii string of the base-10 representation of the number. Even wilder is that the entire region after the length up to 0x80061ff is padded with ascii space characters, and terminated with \r\n.

After exploring a small amount further, I decided to turn my attention to the display unit. The majority of the code in the controller appears to be the FOC motor control code, and I didn’t feel particularly comfortable modifying the safety critical part of the device, especially after discovering that the controller contains some fairly reasonable safety precautions, such as shutting down if the display stops sending valid throttle positions after a short period.

Display unit

Cracking open the display unit required much more effort than the controller. It’s constructed from a reasonably tough and thick (2mm) injection molded body, so I used a dremel to cut into the back side. I had assumed the front screen cover was heat welded on, and so I also started using a dremel around the edge, but once I had cut a slot and had some leverage, I was able to simply pry the cover off as it was only glued.

The board for the display was quite interesting as it had several unused through hole pin header rows and multiple microcontrollers. I identified the chips to be the following:

1. Main MCU: AT32F415
2. Bluetooth MCU: CH573
3. NFC reader IC: FM17520
4. CAN Transceiver
5. SPI flash chip: W25Q128FV

One debug header was the SWD port for the main MCU, so I repeated the process of dumping the firmware there. Another provided access to the SPI flash, so I also dumped this, but it only contained only the bitmap images used by the GUI shown on the display.

The display firmware is structure similarly to the control unit, with a bootloader which is capable of receiving firmware updates over the CAN bus.

1. The display unit firmware is structured as a bootloader and a main application at 0x8008000.
2. The GUI is drawn using SEGGER EMWin.
3. The bluetooth MCU communicates over GPIOA 2 and 3 using UART at 57500k, using a simple framing scheme. When a bluetooth attribute is read, the CH573 sends a request message with a number indicating a handler in the main MCU firmware. The main MCU sends back a response message with the same command number and the response body.
4. The NFC module also communicates over UART at 115200k, with a slightly different protocol. I didn’t look into this much further.
5. The button panel on the handlebars of the scooter communicates with the display unit also over UART, at 9600k. The only message it sends is a simple bitfield of the buttons that are pressed. Interestingly, it handles the blinking of the indicators itself; It blinks the lights and also has two bits in its message which indicates the blinker state. It appears to also be able to receive firmware updates.
6. The CAN bus is connected over pins GPIOA 11 and 12.
7. The display is a ST7796 controller, connected over a parallel interface; All 16 pins on GPIOB are used as a parallel data bus, which allows the firmware to update the state of all pins in just one instruction.
8. The ADC reads from three channels: An ambient light sensor on ch12, the throttle voltage on ch13, and the battery voltage on ch15. The firmware only reads the battery voltage to trigger an error message when it is too low, for all other usages of the battery level the firmware reads a variable updated by a CAN message sent by the battery. (Yeah, the battery is on the bus.)
9. The firmware of the display unit is, like the controller, updated over CAN. And again like the controller, the actual update code lives in the bootloader; The application firmware simply reboots itself if it sees an update initiation message, the bootloader then sees the next message and starts the update process. Yes, this also means that it’s possible to modify the firmware of any scooter without authentication :)))))

Initially the display firmware was a pain to reverse engineer, the version of Ghidra that I was using had a bug which caused it to not properly tag function pointers located in areas identified as data, due to the pointers having their lower bits set (indicating that the function uses THUMB instructions). Since the firmware is structured around tables of callbacks - for CAN, bluetooth, and GUI screens - I was unable to locate the callers of a lot of functions. By luck I at some point encountered the function which scans through the CAN handlers table and was able to ascertain the structure of the CAN handler table, and since every entry in the table specifies the ID to match on, and optionally an interval and a tx and/or rx callback, I was now able to quickly locate the corresponding code for each CAN message that I observed.

Through extensive cross referencing of both the display and controller firmware, I was able to build up a mostly complete understanding of the CAN messages, the only messages I didn’t complete were some related to the apple find my feature, which I’m not particularly interested in because I don’t have an iphone and instead built my own tracker device using openhaystack, which has the extra benefit of not triggering any ‘tracker following’ messages as it rotates identity every 30 minutes :)

Next up was figuring out the GPIO and peripheral configurations, which I’d need to begin writing my own firmware. Thankfully this is actually pretty easy as the firmware is using the manufacturer provided peripheral library and also didn’t use any form of LTO when compiling, so the decompilation output for the compiled HAL provided functions very closely matches the source.

Using this technique of matching up decompiled library functions with source code, and using the name and type information obtained by doing so to discover peripheral configs, allowed me to fully map out all the GPIO pins and the configurations of all the peripherals..

Another thing that aided in my reverse engineering was that the firmware had left in a debug menu (it seems to be unreachable from the actual firmware, but the code is still there). The debug menu displays some button and headlight statuses, so I was instantly able to fill out a ‘button state’ enum.

At this point I had pretty much figured out enough information to begin writing my own firmware; The CAN messages required to operate the motor controller were fully mapped out, as were the GPIO pins and peripheral configurations, and I’d also reverse engineered the UART protocol of the bluetooth MCU. I’d even put together a block diagram of all the individual components of the scooter that communicate:

Running my own firmware on the cracked open display unit would be trivial, as I can just use a debug probe to flash it. But to get my firmware onto a usable display unit I’d need to reverse engineer the firmware update process.

Firmware updates

Thankfully (for me) the firmware update process ended up being extremely simple, with no cryptography involved and the main lifecycle of a firmware update living entirely within one function in the bootloader.

A firmware update starts in a CAN message handler for ID 0x384. If the message is then the firmware resets, and if the message is then the scooter erases the flash regions used to store the VIN and scooter configuration.

The device performing the firmware update then continues to send messages until the bootloader starts up, sees an update initiation message, and replies with . The updater device then sends 64 byte chunks spread over 9 CAN 0x384 frames, where each frame has the following structure:

• Frame 0
• Frame 1..9
• Frame 9

The CRC is CRC-16-CCITT over the data. The data of each chunk is padded with zeros to make 64 bytes before calculating the CRC. sequence is an unsigned byte, starting at 0 and incrementing for each chunk transmitted, after 0xFF it wraps to 0.

The first chunk is not the first 64 bytes of the firmware, but instead the update file name (for example: AT_R2_JHZY_GT1_GE_FM_HW02_4.0.2) as a null terminated string, followed by the firmware length as a base-10 encoded, null terminated string. The bootloader replies to the first chunk four times with , and all subsequent chunks with one .

After the first chunk is sent, the updater device then sends the firmware image a chunk at a time. The scooter replies with one message after the last CAN message of a frame is sent and the CRC is validated. After the firmware has been transmitted, the updater sends , which triggers a reboot of the display unit. The update mechanism directly writes over the application image in flash, so a failed update will brick the display. However, the bootloader always checks for the presence of packets when powering up, allowing a firmware update to begin even if the application code isn’t functional.

In summary, the update process follows this sequence diagram (you can tell I’m having fun with typst here :)):

To actually do the firmware update, I extended the CAN dumping firmware that I wrote earlier into this, which simply flashes a firmware image embedded inside.

Great, I can now update the firmware on the device. To confirm this worked I tried it out with the firmware image I’d dumped from the cracked open device to begin with, and it worked first time.

Rewrite it in rust

Now I could begin writing some firmware in Rust. There was a small problem though, the display unit MCU is the AT32F415, which is a STM clone, but it seems to not be a clone of a specific STM chip, but instead a mish-mash of STM32 peripherals, most appear to match up with the STM32F1, but the RTC seems to be from a STM32F3. This is annoying because it means I can’t just jumpstart to writing firmware using Embassy, instead I need to first build my own HAL^4.

Kossnikita had already started on this using a fork of stm32-rs, so I was thankfully able to take this and start adding support for the peripherals I needed. I must admit I mostly cheated here; for most of the peripherals I started by taking the implementation from Embassy, and then I, with both the datasheet of the stm32f1 and the at32f415 open, updated the peripheral code to match the register names used by the AT32. There’s very likely a better way here, such as adding the chip as an entry in stm32-metapac, which is a subproject of Embassy which processes SVD files to create PAC^5 crates, but I initially assumed the AT32 was more different than it is.

I started by bringing up each peripheral, the clocks and timers first, as a timer allows me to add an embassy-time-driver implementation. Then the ADC, external GPIO interrupts, UART, CAN, and RTC peripherals. With the HAL drivers implemented I could then start writing code to drive the display, read the ADC inputs, and talk over the CAN and UART buses.

Bringing up the display was entirely straightforward, using the mipidsi crate for the display driver, all I had to do myself was add a ParallelInterface implementation in the HAL that allows writing a u16 to all the GPIO pins in one operation:

1
/// A bus of gpio pins
2
///
3
/// SHIFT: which range of pins are we operating on: 0 => 0..16, 8 => 8..16
4
/// MASK: bitmask used to select which pins are members of this bus. The mask is unshifted.
5
pub struct Bus<const P: char, const SHIFT: u8, const MASK: u16, MODE = DefaultMode> {
6
    _mode: PhantomData<MODE>,
7
}
8
9
impl<const P: char, const SHIFT: u8, const MASK: u16, MODE> Bus<P, SHIFT, MASK, MODE> {
10
    fn _set_state(&mut self, state: u16) {
11
        unsafe {
12
            (*Gpio::<P>::ptr()).odt().modify(|r, w| {
13
                // we only need to read the previous state if the mask doesn't
14
                // cover everything.
15
                let prev = if const { MASK & 0xFFFF != 0xFFFF } {
16
                    r.bits() & !(MASK as u32)
17
                } else {
18
                    0
19
                };
20
                let new = ((state << SHIFT) & MASK) as u32;
21
                w.bits(prev | new)
22
            });
23
        }
24
    }
25
26
    fn _get_state(&self) -> u16 {
27
        unsafe {
28
            let unshifted = (*Gpio::<P>::ptr()).odt().read().bits() & !(MASK as u32);
29
            (unshifted >> SHIFT) as u16
30
        }
31
    }
32
}
33
34
impl<const P: char, const SHIFT: u8, const MASK: u16> mipidsi::interface::OutputBus
35
    for Bus<P, SHIFT, MASK, Output>
36
{
37
    type Word = u16;
38
39
    const KIND: mipidsi::interface::InterfaceKind = InterfaceKind::Parallel16Bit;
40
41
    type Error = Infallible;
42
43
    #[inline(always)]
44
    fn set_value(&mut self, value: Self::Word) -> Result<(), Self::Error> {
45
        self.set_state(value);
46
        Ok(())
47
    }
48
}

1
/// A bus of gpio pins
2
///
3
/// SHIFT: which range of pins are we operating on: 0 => 0..16, 8 => 8..16
4
/// MASK: bitmask used to select which pins are members of this bus. The mask is unshifted.
5
pub struct Bus<const P: char, const SHIFT: u8, const MASK: u16, MODE = DefaultMode> {
6
    _mode: PhantomData<MODE>,
7
}
8
9
impl<const P: char, const SHIFT: u8, const MASK: u16, MODE> Bus<P, SHIFT, MASK, MODE> {
10
    fn _set_state(&mut self, state: u16) {
11
        unsafe {
12
            (*Gpio::<P>::ptr()).odt().modify(|r, w| {
13
                // we only need to read the previous state if the mask doesn't
14
                // cover everything.
15
                let prev = if const { MASK & 0xFFFF != 0xFFFF } {
16
                    r.bits() & !(MASK as u32)
17
                } else {
18
                    0
19
                };
20
                let new = ((state << SHIFT) & MASK) as u32;
21
                w.bits(prev | new)
22
            });
23
        }
24
    }
25
26
    fn _get_state(&self) -> u16 {
27
        unsafe {
28
            let unshifted = (*Gpio::<P>::ptr()).odt().read().bits() & !(MASK as u32);
29
            (unshifted >> SHIFT) as u16
30
        }
31
    }
32
}
33
34
impl<const P: char, const SHIFT: u8, const MASK: u16> mipidsi::interface::OutputBus
35
    for Bus<P, SHIFT, MASK, Output>
36
{
37
    type Word = u16;
38
39
    const KIND: mipidsi::interface::InterfaceKind = InterfaceKind::Parallel16Bit;
40
41
    type Error = Infallible;
42
43
    #[inline(always)]
44
    fn set_value(&mut self, value: Self::Word) -> Result<(), Self::Error> {
45
        self.set_state(value);
46
        Ok(())
47
    }
48
}

We can then declare the pins used in the display as rust types:

1
pub type Bus = at32f4xx_hal::gpio::Bus<'B', 0, 0xFFFF, Output>;
2
pub type CsPin = Pin<'C', 13, Output>;
3
pub type DcPin = Pin<'C', 14, Output>;
4
pub type RdPin = Pin<'C', 0, Output>;
5
pub type WrPin = Pin<'C', 15, Output>;
6
pub type RstPin = Pin<'C', 1, Output>;
7
pub type Backlight = PwmChannel<at32f4xx_hal::pac::TMR2, 0>;
8
pub type InnerDisplay = mipidsi::Display<
9
    mipidsi::interface::ParallelInterface<Bus>,
10
    mipidsi::models::ST7796,
11
    RstPin,
12
>;
13
14
pub fn init(
15
    mut rd: RdPin,
16
    mut cs: CsPin,
17
    dc: DcPin,
18
    wr: WrPin,
19
    rst: RstPin,
20
    bus: Bus,
21
    delay: &mut SysDelay,
22
    backlight: Backlight,
23
) -> Display {
24
    cs.set_low();
25
    rd.set_high();
26
27
    let interface = mipidsi::interface::ParallelInterface::new(bus, dc, wr);
28
    let mut display = mipidsi::Builder::new(mipidsi::models::ST7796, interface)
29
        .reset_pin(rst)
30
        .invert_colors(mipidsi::options::ColorInversion::Inverted)
31
        .orientation(mipidsi::options::Orientation {
32
            rotation: mipidsi::options::Rotation::Deg0,
33
            mirrored: true,
34
        })
35
        .color_order(mipidsi::options::ColorOrder::Bgr)
36
        .init(delay)
37
        .unwrap();
38
39
    Display {
40
        _cs_pin: cs,
41
        _rd_pin: rd,
42
        inner: display,
43
        backlight,
44
    }
45
}

1
pub type Bus = at32f4xx_hal::gpio::Bus<'B', 0, 0xFFFF, Output>;
2
pub type CsPin = Pin<'C', 13, Output>;
3
pub type DcPin = Pin<'C', 14, Output>;
4
pub type RdPin = Pin<'C', 0, Output>;
5
pub type WrPin = Pin<'C', 15, Output>;
6
pub type RstPin = Pin<'C', 1, Output>;
7
pub type Backlight = PwmChannel<at32f4xx_hal::pac::TMR2, 0>;
8
pub type InnerDisplay = mipidsi::Display<
9
    mipidsi::interface::ParallelInterface<Bus>,
10
    mipidsi::models::ST7796,
11
    RstPin,
12
>;
13
14
pub fn init(
15
    mut rd: RdPin,
16
    mut cs: CsPin,
17
    dc: DcPin,
18
    wr: WrPin,
19
    rst: RstPin,
20
    bus: Bus,
21
    delay: &mut SysDelay,
22
    backlight: Backlight,
23
) -> Display {
24
    cs.set_low();
25
    rd.set_high();
26
27
    let interface = mipidsi::interface::ParallelInterface::new(bus, dc, wr);
28
    let mut display = mipidsi::Builder::new(mipidsi::models::ST7796, interface)
29
        .reset_pin(rst)
30
        .invert_colors(mipidsi::options::ColorInversion::Inverted)
31
        .orientation(mipidsi::options::Orientation {
32
            rotation: mipidsi::options::Rotation::Deg0,
33
            mirrored: true,
34
        })
35
        .color_order(mipidsi::options::ColorOrder::Bgr)
36
        .init(delay)
37
        .unwrap();
38
39
    Display {
40
        _cs_pin: cs,
41
        _rd_pin: rd,
42
        inner: display,
43
        backlight,
44
    }
45
}

And now we have a Display which we can draw to. By opening up the compiled firmware in Ghidra we can also confirm that the data transmission loop turns into a simple loop which writes a sequence of bytes to a single MMIO register:

1
void __rustcall mipidsi::interface::parallel::send_command<>(ParallelInterface<> *self,u8 command,&[u8] args)
2
3
{
4
  byte *pbVar1;
5
  u8 *puVar2;
6
7
  _DAT_40010c0c = command & 0xff;
8
  _DAT_422202b8 = 1;
9
  _DAT_42220238 = 1;
10
  pbVar1 = args.data_ptr;
11
  for (puVar2 = args.len; puVar2 != 0x0; puVar2 = puVar2 + -1) {
12
    _DAT_40010c0c = *pbVar1;
13
    pbVar1 = pbVar1 + 1;
14
    _DAT_422202bc = 1;
15
    _DAT_4222023c = 1;
16
  }
17
  return;
18
}

1
void __rustcall mipidsi::interface::parallel::send_command<>(ParallelInterface<> *self,u8 command,&[u8] args)
2
3
{
4
  byte *pbVar1;
5
  u8 *puVar2;
6
7
  _DAT_40010c0c = command & 0xff;
8
  _DAT_422202b8 = 1;
9
  _DAT_42220238 = 1;
10
  pbVar1 = args.data_ptr;
11
  for (puVar2 = args.len; puVar2 != 0x0; puVar2 = puVar2 + -1) {
12
    _DAT_40010c0c = *pbVar1;
13
    pbVar1 = pbVar1 + 1;
14
    _DAT_422202bc = 1;
15
    _DAT_4222023c = 1;
16
  }
17
  return;
18
}

With the display working, I next worked on implementing encoding and decoding of the CAN and bluetooth protocols. For this I used deku as it allows you to declare byte and bit level parsers for structs using a quite concise macro^6:

1
/// 513
2
#[derive(deku::DekuRead, deku::DekuSize, defmt::Format, Clone, PartialEq, Eq)]
3
#[cfg_attr(test, derive(deku::DekuWrite, Debug))]
4
#[deku(bit_order = "lsb", endian = "little")]
5
pub struct ControllerSpeed {
6
    /// In km/h * 100
7
    #[deku(pad_bytes_after = "2")]
8
    pub motor_speed: u16,
9
10
    #[deku(bits = 1)]
11
    pub walk_mode: bool,
12
13
    #[deku(bits = 1)]
14
    pub headlight_on: bool,
15
16
    #[deku(bits = 1, pad_bits_after = "5")]
17
    pub brake_light_on: bool,
18
}
19
20
#[test]
21
fn test_display_throttle() {
22
    let mut buf = [0u8; 8];
23
    deser_roundtrip(&mut buf, &DisplayThrottle::new(511, false, false, 0));
24
    assert_eq!(buf, [0xff, 0b1, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]);
25
26
    deser_roundtrip(&mut buf, &DisplayThrottle::new(511, true, false, 0));
27
    assert_eq!(buf, [0xff, 0b011, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]);
28
29
    deser_roundtrip(&mut buf, &DisplayThrottle::new(511, true, true, 2));
30
    assert_eq!(buf, [0xff, 0b111, 0x00, 0x02, 0x02, 0x00, 0x00, 0x00]);
31
32
    deser_roundtrip(&mut buf, &DisplayThrottle::new(1, false, true, 2));
33
    assert_eq!(buf, [0x01, 0b100, 0x00, 0x02, 0x02, 0x00, 0x00, 0x00]);
34
35
    deser_roundtrip(&mut buf, &DisplayThrottle::new(256, false, true, 2));
36
    assert_eq!(buf, [0x00, 0b101, 0x00, 0x02, 0x02, 0x00, 0x00, 0x00]);
37
}

1
/// 513
2
#[derive(deku::DekuRead, deku::DekuSize, defmt::Format, Clone, PartialEq, Eq)]
3
#[cfg_attr(test, derive(deku::DekuWrite, Debug))]
4
#[deku(bit_order = "lsb", endian = "little")]
5
pub struct ControllerSpeed {
6
    /// In km/h * 100
7
    #[deku(pad_bytes_after = "2")]
8
    pub motor_speed: u16,
9
10
    #[deku(bits = 1)]
11
    pub walk_mode: bool,
12
13
    #[deku(bits = 1)]
14
    pub headlight_on: bool,
15
16
    #[deku(bits = 1, pad_bits_after = "5")]
17
    pub brake_light_on: bool,
18
}
19
20
#[test]
21
fn test_display_throttle() {
22
    let mut buf = [0u8; 8];
23
    deser_roundtrip(&mut buf, &DisplayThrottle::new(511, false, false, 0));
24
    assert_eq!(buf, [0xff, 0b1, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]);
25
26
    deser_roundtrip(&mut buf, &DisplayThrottle::new(511, true, false, 0));
27
    assert_eq!(buf, [0xff, 0b011, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]);
28
29
    deser_roundtrip(&mut buf, &DisplayThrottle::new(511, true, true, 2));
30
    assert_eq!(buf, [0xff, 0b111, 0x00, 0x02, 0x02, 0x00, 0x00, 0x00]);
31
32
    deser_roundtrip(&mut buf, &DisplayThrottle::new(1, false, true, 2));
33
    assert_eq!(buf, [0x01, 0b100, 0x00, 0x02, 0x02, 0x00, 0x00, 0x00]);
34
35
    deser_roundtrip(&mut buf, &DisplayThrottle::new(256, false, true, 2));
36
    assert_eq!(buf, [0x00, 0b101, 0x00, 0x02, 0x02, 0x00, 0x00, 0x00]);
37
}

The neat thing about doing this in rust is that I could then take these definitions and use them in a completely different program to decode the CAN logs into something human readable:

1
L1 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
2
L2 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3094 })
3
L3 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
4
L4 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
5
L5 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3094 })
6
L6 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
7
L7 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
8
L8 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
9
L9 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
10
L10 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
11
L11 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48499, current_ma: 3075 })
12
L12 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
13
L13 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
14
L14 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
15
L15 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
16
L16 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
17
L17 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48499, current_ma: 3075 })
18
L18 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
19
L19 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
20
L20 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
21
L21 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
22
L22 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
23
L23 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48498, current_ma: 3055 })
24
L24 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
25
L25 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
26
L26 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
27
L27 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
28
L28 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
29
L29 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48498, current_ma: 3055 })
30
L30 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
31
L31 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
32
L32 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
33
L33 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
34
L34 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
35
L35 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3049 })
36
L36 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
37
L37 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
38
L38 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
39
L39 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
40
L40 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
41
L41 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3049 })
42
L42 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
43
L43 id=774 ext=false from=display DisplayThrottle(DisplayThrottle { throttle: 85, left_blinker: false, right_blinker: false, speed_limit: 0, magic: DekuConst })
44
L44 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
45
L45 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
46
L46 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
47
L47 id=768 ext=false from=display DisplaySpeedMode(DisplaySpeedMode { mode: 0, mode_high: 90, headlight: 100, magic: Normal, speed_mode_byte: 0, walk_counter: 0 })
48
L48 id=494 ext=false from=display unknown [60, 00, 00, 00, 00, 00, 00, 00]
49
L49 id=495 ext=false from=unknown unknown [4c, 44, 2e, 43, 52, 2e, 53, 38]
50
L50 id=495 ext=false from=unknown unknown [30, 37, 2e, 43, 2e, 32, 2e, 31]
51
L51 id=495 ext=false from=unknown unknown [45, 47, 2e, 32, 2e, 32, 2e, 31]
52
L52 id=495 ext=false from=unknown unknown [31, 00, 00, 00, 00, 00, 00, 00]
53
L53 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
54
L54 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
55
L55 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
56
L56 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
57
L57 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
58
L58 id=768 ext=false from=display DisplaySpeedMode(DisplaySpeedMode { mode: 0, mode_high: 90, headlight: 100, magic: Normal, speed_mode_byte: 0, walk_counter: 0 })
59
L59 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
60
L60 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
61
L61 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
62
L62 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
63
L63 id=1856 ext=true from=display unknown [4b, 00]
64
L64 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
65
L65 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3044 })
66
L66 id=1857 ext=true from=unknown unknown [4b, 00, 00, 00, 69, 99, 52, 42]
67
L67 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
68
L68 id=1860 ext=true from=display unknown [01]
69
L69 id=1861 ext=true from=battery unknown [01, 15, 57, 20, 50, 59, 54, 34]
70
L70 id=774 ext=false from=display DisplayThrottle(DisplayThrottle { throttle: 84, left_blinker: false, right_blinker: false, speed_limit: 0, magic: DekuConst })
71
L71 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: true, brake_light_on: false })
72
L72 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 8191 })
73
L73 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
74
L74 id=768 ext=false from=display DisplaySpeedMode(DisplaySpeedMode { mode: 0, mode_high: 90, headlight: 100, magic: Normal, speed_mode_byte: 0, walk_counter: 0 })

1
L1 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
2
L2 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3094 })
3
L3 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
4
L4 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
5
L5 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3094 })
6
L6 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
7
L7 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
8
L8 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
9
L9 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
10
L10 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
11
L11 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48499, current_ma: 3075 })
12
L12 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
13
L13 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
14
L14 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
15
L15 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
16
L16 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
17
L17 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48499, current_ma: 3075 })
18
L18 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
19
L19 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
20
L20 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
21
L21 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
22
L22 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
23
L23 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48498, current_ma: 3055 })
24
L24 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
25
L25 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
26
L26 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
27
L27 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
28
L28 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
29
L29 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48498, current_ma: 3055 })
30
L30 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
31
L31 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
32
L32 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
33
L33 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
34
L34 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
35
L35 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3049 })
36
L36 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
37
L37 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
38
L38 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
39
L39 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
40
L40 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
41
L41 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3049 })
42
L42 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
43
L43 id=774 ext=false from=display DisplayThrottle(DisplayThrottle { throttle: 85, left_blinker: false, right_blinker: false, speed_limit: 0, magic: DekuConst })
44
L44 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: false, brake_light_on: false })
45
L45 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 33 })
46
L46 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
47
L47 id=768 ext=false from=display DisplaySpeedMode(DisplaySpeedMode { mode: 0, mode_high: 90, headlight: 100, magic: Normal, speed_mode_byte: 0, walk_counter: 0 })
48
L48 id=494 ext=false from=display unknown [60, 00, 00, 00, 00, 00, 00, 00]
49
L49 id=495 ext=false from=unknown unknown [4c, 44, 2e, 43, 52, 2e, 53, 38]
50
L50 id=495 ext=false from=unknown unknown [30, 37, 2e, 43, 2e, 32, 2e, 31]
51
L51 id=495 ext=false from=unknown unknown [45, 47, 2e, 32, 2e, 32, 2e, 31]
52
L52 id=495 ext=false from=unknown unknown [31, 00, 00, 00, 00, 00, 00, 00]
53
L53 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
54
L54 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
55
L55 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
56
L56 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
57
L57 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
58
L58 id=768 ext=false from=display DisplaySpeedMode(DisplaySpeedMode { mode: 0, mode_high: 90, headlight: 100, magic: Normal, speed_mode_byte: 0, walk_counter: 0 })
59
L59 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
60
L60 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
61
L61 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
62
L62 id=495 ext=false from=unknown unknown [00, 00, 00, 00, 00, 00, 00, 00]
63
L63 id=1856 ext=true from=display unknown [4b, 00]
64
L64 id=1024 ext=false from=battery BatteryCommandState(BatteryCommandState { command: 16384, state: 1159, estimated_range: 0 })
65
L65 id=1025 ext=false from=battery BatteryVoltageCurrent(BatteryVoltageCurrent { voltage_mv: 48500, current_ma: 3044 })
66
L66 id=1857 ext=true from=unknown unknown [4b, 00, 00, 00, 69, 99, 52, 42]
67
L67 id=1028 ext=false from=battery BatteryCapacityTemp(BatteryCapacityTemp { capacity_mah: 20000, battery_charged: true, battery_charging: false, battery_temp: 270 })
68
L68 id=1860 ext=true from=display unknown [01]
69
L69 id=1861 ext=true from=battery unknown [01, 15, 57, 20, 50, 59, 54, 34]
70
L70 id=774 ext=false from=display DisplayThrottle(DisplayThrottle { throttle: 84, left_blinker: false, right_blinker: false, speed_limit: 0, magic: DekuConst })
71
L71 id=513 ext=false from=controller ControllerSpeed(ControllerSpeed { motor_speed: 0, walk_mode: false, headlight_on: true, brake_light_on: false })
72
L72 id=515 ext=false from=controller ControllerSpeedMode(ControllerSpeedMode { unknown: 8191 })
73
L73 id=528 ext=false from=controller ControllerSpeedLimit(ControllerSpeedLimit { speed_limit: false })
74
L74 id=768 ext=false from=display DisplaySpeedMode(DisplaySpeedMode { mode: 0, mode_high: 90, headlight: 100, magic: Normal, speed_mode_byte: 0, walk_counter: 0 })

Actor-modelling

Now that the protocols are implemented, it becomes quite easy to write state machines using Embassy to handle incoming messages (both external messages from the CAN bus or bluetooth MCU, or internally defined messages for communicating button presses, events triggered by the UI, and ADC readings) and update relevant state. Overall, using the actor model for firmware is really quite a breeze, when all tasks communicate over well defined interfaces instead of reading and writing to shared global memory, reasoning about the system becomes simplified, and in my case, writing an emulator tool to test the GUI proved easy.

In the end, I ended up with this set of actors and relationships:

The ADC Task

This task reads the ADC periodically, and publishes readings onto a channel that other tasks can subscribe to.

1
pub static ADC_READINGS: embassy_sync::pubsub::PubSubChannel<embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex, AdcReading, 4, 4, 1> = embassy_sync::pubsub::PubSubChannel::new();
2
3
pub static THROTTLE_READINGS: embassy_sync::watch::Watch<embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex, Throttle, 4> = embassy_sync::watch::Watch::new();
4
5
pub static AMBIENT_READINGS: embassy_sync::watch::Watch<embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex, AmbientLight, 4> = embassy_sync::watch::Watch::new();
6
7
async fn adc_task_(
8
    mut adc: Adc<ADC1>,
9
    // ambient light
10
    ch12: Pin<'C', 2, Analog>,
11
12
    // throttle
13
    ch13: Pin<'C', 3, Analog>,
14
) {
15
    let mut do_sample_ticker = embassy_time::Ticker::every(Duration::from_millis(50));
16
17
    let state_reading_ch = ADC_READINGS.publisher().unwrap();
18
    let throttle_reading_ch = THROTTLE_READINGS.sender();
19
    let ambient_reading_ch = AMBIENT_READINGS.sender();
20
21
    // the ambient light level is averaged so that it doesn't flicker
22
    let mut ambient_light_averager = MovingAverage::<u16, u32, 16>::new();
23
24
    loop {
25
        // sample the throttle and ambient light every 50ms
26
        do_sample_ticker.next().await;
27
28
        defmt::trace!("ADC measuring ambient");
29
        let val = adc.convert(&ch12, SampleTime::Cycles_480).await;
30
        let avg = ambient_light_averager.average(val);
31
        let ambient_light = AmbientLight::from_raw(avg);
32
        state_reading_ch
33
            .publish(AdcReading::AmbientLight(ambient_light))
34
            .await;
35
        ambient_reading_ch.send(ambient_light);
36
37
        defmt::trace!("ADC measuring throttle");
38
        let val = adc.convert(&ch13, SampleTime::Cycles_480).await;
39
        let thr = Throttle::from_raw(val);
40
        state_reading_ch.publish(AdcReading::Throttle(thr)).await;
41
        throttle_reading_ch.send(thr);
42
    }
43
}

1
pub static ADC_READINGS: embassy_sync::pubsub::PubSubChannel<embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex, AdcReading, 4, 4, 1> = embassy_sync::pubsub::PubSubChannel::new();
2
3
pub static THROTTLE_READINGS: embassy_sync::watch::Watch<embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex, Throttle, 4> = embassy_sync::watch::Watch::new();
4
5
pub static AMBIENT_READINGS: embassy_sync::watch::Watch<embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex, AmbientLight, 4> = embassy_sync::watch::Watch::new();
6
7
async fn adc_task_(
8
    mut adc: Adc<ADC1>,
9
    // ambient light
10
    ch12: Pin<'C', 2, Analog>,
11
12
    // throttle
13
    ch13: Pin<'C', 3, Analog>,
14
) {
15
    let mut do_sample_ticker = embassy_time::Ticker::every(Duration::from_millis(50));
16
17
    let state_reading_ch = ADC_READINGS.publisher().unwrap();
18
    let throttle_reading_ch = THROTTLE_READINGS.sender();
19
    let ambient_reading_ch = AMBIENT_READINGS.sender();
20
21
    // the ambient light level is averaged so that it doesn't flicker
22
    let mut ambient_light_averager = MovingAverage::<u16, u32, 16>::new();
23
24
    loop {
25
        // sample the throttle and ambient light every 50ms
26
        do_sample_ticker.next().await;
27
28
        defmt::trace!("ADC measuring ambient");
29
        let val = adc.convert(&ch12, SampleTime::Cycles_480).await;
30
        let avg = ambient_light_averager.average(val);
31
        let ambient_light = AmbientLight::from_raw(avg);
32
        state_reading_ch
33
            .publish(AdcReading::AmbientLight(ambient_light))
34
            .await;
35
        ambient_reading_ch.send(ambient_light);
36
37
        defmt::trace!("ADC measuring throttle");
38
        let val = adc.convert(&ch13, SampleTime::Cycles_480).await;
39
        let thr = Throttle::from_raw(val);
40
        state_reading_ch.publish(AdcReading::Throttle(thr)).await;
41
        throttle_reading_ch.send(thr);
42
    }
43
}

To handle converting raw ADC readings to usable numbers, I use the following newtype pattern:

1
#[derive(Eq, PartialEq, Default, defmt::Format, Clone, Copy, Debug)]
2
pub struct Throttle(pub u16);
3
4
impl Throttle {
5
    pub const INITIAL: Self = Self(0);
6
7
    // value we report to the controller when throttle is fully depressed
8
    const OUT_MAX: u32 = 360;
9
10
    fn from_raw(raw: u16) -> Self {
11
        // value the adc reads when throttle is fully depressed
12
        const MAX_RAW: u32 = 2820;
13
14
        // value the adc reads when the throttle is unpressed
15
        const MIN_RAW: u32 = 730;
16
17
        Self(
18
            (raw as u32)
19
                .clamp(MIN_RAW, MAX_RAW)
20
                .saturating_sub(MIN_RAW)
21
                .saturating_mul(Self::OUT_MAX)
22
                .saturating_div(MAX_RAW - MIN_RAW)
23
                .saturating_truncate(),
24
        )
25
    }
26
27
    pub(crate) fn for_bluetooth(&self) -> u8 {
28
        const MAX_BT: u32 = 146;
29
30
        (self.0 as u32)
31
            .saturating_mul(MAX_BT)
32
            .saturating_div(Self::OUT_MAX)
33
            .saturating_truncate()
34
    }
35
36
    pub fn adjust_for_speed_limit(
37
        &self,
38
        // current speed limit setpoint (e.g. 271)
39
        speed_limit: u16,
40
        // speed limit set on the controller
41
        // (250/350/450). for a speed_limit of 271
42
        // this should be 350.
43
        controller_speed_limit: u16,
44
    ) -> u16 {
45
        // This is just a linear scale for now. I need to find how the speed
46
        // actually responds over throttle values.
47
        (self.0 as u32)
48
            .saturating_mul(speed_limit as u32)
49
            .saturating_div(controller_speed_limit as u32)
50
            .saturating_truncate()
51
    }
52
}