UPDATE: This code in this article has been archived in the pre-lvgl branch of pinetime-rust-mynewt. The pinetime-rust-mynewt firmware has been revamped to support Rust Watch Faces on LVGL. Check out the updates

Using only a Raspberry Pi, we can debug the firmware on PineTime Smart Watch: Step into the flashed program line by line, set a breakpoint to pause execution at a line, inspect variables at runtime, … Just like the Embedded Pros!

It’s a great way to learn how real IoT gadgets are created… At a fraction of the cost of professional embedded tools and workstations!

Here are the steps to configure a Raspberry Pi (1, 2, 3 or 4, with 1 GB RAM or more) for debugging the Rust+Mynewt Firmware for PineTime…

Build and Flash Firmware to PineTime

First we prepare PineTime for development by erasing the demo firmware and replacing it by our own firmware. This only needs to be done once.

Follow the instructions in the article “Build and Flash Rust+Mynewt Firmware for PineTime Smart Watch” under the following sections…

1. “Connect PineTime to Raspberry Pi”
2. “Remove PineTime Flash Protection”

If you have installed the PineTime tools before 23 Jan 2020, please redo the above steps to get the latest updates

🛈 What is “flash memory” / “flashing” / “firmware”? Read this

1️⃣ Launch VSCode by clicking the Raspberry Pi Menu (top left corner) → Programming → Code OSS Headmelted

Launching VSCode on Raspberry Pi

In VSCode, click File → Open Folder

Under Home, select the folder pinetime-rust-mynewt and click OK

When prompted to open the workspace, click Open Workspace

When prompted to install Extension Recommendations, click Install All

Ignore the message Unable To Watch For File Changes. Close the message when it appears.

2️⃣ At the lower left corner, there is a panel Task Runner. Click the panel to display the tasks.

In the Task Runner, click [1] Build Bootloader

When the Terminal Panel appears, right-click the Terminal tab, select Move Panel Right

After the building the Bootloader, we should see Done…

Ignore the message There Are Task Errors

🛈 What is a Bootloader? Read this

3️⃣ In the Task Runner, click [2] Build Application

After the building the Application, we should see Done…

If you see the message Undefined Reference To Main, click [2] Build Application again and it should succeed.

4️⃣ In the Task Runner, click [3] Image Application

After the creating the Firmware Image, we should see Done…

5️⃣ In the Task Runner, click [4] Flash Bootloader

After flashing the Bootloader Firmware to PineTime, we should see Done…

6️⃣ In the Task Runner, click [5] Flash Application

After the flashing the Application Firmware to PineTime, we should see Done…

7️⃣ Our Rust application starts running on PineTime…

Our Rust Application rendering graphics and text to the PineTime display

Here are the debugging messages generated by our application…

8️⃣ Click the Trash icon 🗑 near the top right to terminate the application. If we click the Close icon ❌ instead of the Trash icon, the next flash or debug command will fail.

Here’s a walkthrough of the steps to Build and Flash Firmware to PineTime…

Debug PineTime Firmware

Now that the Bootloader Firmware and Application Firmware have been flashed, we are ready to debug the firmware on PineTime…

1️⃣ In VSCode, edit the Rust application located at rust/app/src/display.rs

This is a simple function test_display that’s called by our Rust Application to render some text and graphics to the PineTime display. Here’s a good introduction to Rust programming

Change I AM PINETIME to your own message

Click File → Save (or Ctrl-S) to save the file

2️⃣ In the Task Runner, click [2] Build Application

Wait for the Application to be built…

If you see the message Undefined Reference To Main, click [2] Build Application again and it should succeed.

3️⃣ In the Rust function test_display, look for the first line that calls the function draw_to_display (Line 43)

Click the empty space to the left of Line 43. A red dot should appear like this…

We have set a Breakpoint. When PineTime executes the firmware to that point, it will pause the execution.

In a while we’ll discover for ourselves how the PineTime firmware runs:
Reset Handler → main Function → test_display Function

4️⃣ Click Debug → Start Debugging or press F5

This starts the VSCode Debugger and automatically flashes our updated firmware to PineTime.

Click View → Output

In the Output Panel, select Adapter Output

5️⃣ The program has paused at first line of code in our firmware, the Reset Handler.

In the Debug Toolbar, click Continue or press F5

🛈 What’s a Reset Handler? Read this

6️⃣ The debugger now pauses at the first line of the main function that’s defined in rust/app/src/lib.rs

This is the first line of Rust code in our Rust Application, which will call test_display in a while.

In the Debug Toolbar, click Continue or press F5

🛈 What’s a main function? Read this

7️⃣ The debugger pauses at the Breakpoint that we have set earlier…

Now we may inspect the Rust variables live, as our firmware runs.

Expand the Variables Panel at top left to inspect the Rust variables for our graphical objects: background, circle, square, text. We can see the screen coordinates that have been set for each graphical object, as well as the text string.

Below that, the Call Stack Panel shows the callers of this function. Click on a caller to see the calling location.

Output Panel → Adapter Output at right shows the debugging messages generated by our Application…

🛈 Why are the strings mashed together? Read this

8️⃣ Here are the other buttons in the Debug Toolbar…

Debug Toolbar

Continue: Continue execution of our firmware until the next Breakpoint

Step Over: Step over the code line by line. The variables will magically reveal themselves one by one after stepping over each line of code! Here’s how it works… 抖音视频

Step Into: Same as Step Over, except that it steps into functions. Useful for diving into Rust library functions and Mynewt system functions. Here’s how it works… 抖音视频

(In the last part of the video, I clicked the Call Stack to see the variables in the calling function)

Step Out: Continue execution until the current function returns

Restart: Stop the execution and start from the beginning

Stop: Stop the debugger

9️⃣ When’re we done with debugging, click Stop

More about VSCode Debugging

When we modify any code in our Rust Application, we only need to click [2] Build Application before starting the debugger. The debugger will flash our updated firmware automatically to PineTime.

Here’s a walkthrough of the steps to debug PineTime Firmware…

💎 The number of Breakpoints that we may set through the debugger is limited to 2 or 3, constrained by the nRF52 Microcontroller in PineTime. Step Over / Step Into / Step Out also counts as one Breakpoint. So it’s easy to run out of Breakpoints while debugging.

Instead of setting Breakpoints via the debugger, we may trigger an unlimited number of Breakpoints in our Rust code by inserting the line below (here’s an example)

cortex_m::asm::bkpt();

Debug Interactive Firmware for PineTime

Feeling adventurous? Try debugging an interactive application for PineTime… A Rust Application that responds to your touch!

1️⃣ Follow the instructions in the article “Build and Flash Rust+Mynewt Firmware for PineTime Smart Watch” under the section “Advanced Topic: Build druid UI Firmware for PineTime”

Modify Cargo.toml to enable ui_app (and disable display_app). Save the file.

2️⃣ Open the file rust/app/src/ui.rs. This file contains two Rust functions: launch and ui_builder

Set a Breakpoint inside the ui_builder function, at the line that says let text = ...

3️⃣ Click [2] Build Application

Click Debug → Start Debugging or press F5

The flow of firmware execution now becomes…
Reset Handler → main Function → launch Function → ui_builder Function

When execution pauses at Reset Handler and at the main Function, click Continue in the Debug Toolbar, or press F5

When execution pauses at the ui_builder Function, click Step Into a few times

We’ll see that this function goes a lot deeper, from…

1. druid Library, for user interface widgets, to…
2. piet Library, for 2D graphics, to…
3. kurbo Library, for computing curves, to…
4. embedded-graphics Library, for rendering graphics, to…
5. Mynewt OS, for sending rendering commands to the display controller, also for handling touch events from the touchscreen controller

Remember: The Call Stack is always there to help if you get lost!