note-zephyr

Upgrade the Zephyr RTOS "blinky" example with Notecard Communication!

Overview

This example is designed to illustrate the ease of adding Notecard functionality to an existing application, by building on the original Zephyr example, samples/basic/blinky.

Functionally, the modification slows down the processing loop from 1s to 10s, and submits a Note to Notehub indicating the current state of the onboard LED.

Requirements

Hardware

• Blues Wireless Notecard
• Blues Wireless Notecarrier
• Blues Wireless Swan
• STLINK Programmer/Debugger

Software

• Docker
• VSCode
• VSCode "Dev Containers" Extension
• [Windows/Mac Debugging] OpenOCD

Cloudware

• Notehub.io

Getting Setup

Notehub.io

Before you can utilize this example, you must set up a free account (no credit card required) on Notehub.io. Once you have created your account, then you need to create a project to serve as an endpoint for the Notes that are tracking the state of the LED.

Once you have a project, you will need to update the define named PROJECT_UID in main.c with the UID of the project you have just created.

After the Notecard has connected to Notehub, you can look inside the project and see a device named zephyr-blink. The Notecard will be running in continuous mode, which will allow it to maintain a constant cellular connection. continuous mode offers the lowest latency possible for sending messages to Notehub, but it comes at the cost of battery life. Fortunately, this is typically not a concern while bench testing, because you are plugged into USB power.

For more information about the Notecard API and examples, please visit our developer site.

Cloning the Repository

This repository contains the note-c library as a submodule. Use the following command to clone both repositories simultaneously.

git clone https://github.com/blues/note-zephyr.git --recursive

If you cloned without the --recursive flag, then you can update the note-c submodule separately, using the following two commands:

git submodule init
git submodule update

Building the Dev Container

WARNING: This step is critical to ensure you correctly build the Dev Container image.

Linux:

To enable flashing and debugging from the container on Linux, you will need to provide access to the USB controller of the host machine.

Perform the following steps, in order to provide USB access:

1. Open ./.devcontainer/devcontainer.json.

2. Uncomment the runArgs section:

   // Uncomment the following section if your host machine is running Linux
   "runArgs": [
       "--device=/dev/bus/usb/"
   ],

   NOTE: At the time of writing, it is not possible to share the host USB from Windows and Mac computers.

Windows/Mac (x86_64):

Ensure Docker Desktop is running.

ARM 64 (aarch64):

1. Open ./.devcontainer/devcontainer.json.

2. Uncomment the args object in the build section:

   // Uncomment the following section if your host machine silicon is ARM64
   "args": {
       "HOST_ARCH":"aarch64"
   },

NOTE: If you failed to properly update devcontainer.json before opening the Dev Container, you may need to purge your docker build cache before trying again.

$ docker system prune
WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all dangling images
  - all dangling build cache

Are you sure you want to continue? [y/N] y

Building and Running

Compiling

1. Open this folder in VSCode.
2. Reopen the folder in the Dev Container.
   1. Press the hotkey combination, Ctrl+Shift+P (Mac: Cmd+Shift+P).
   2. Select Dev Containers: Rebuild and Reopen in Container from the command palette drop-down menu.
3. Build the binary using one of the following options:
   • Press the hotkey combination, Ctrl+Shift+B (Mac: Cmd+Shift+B).
   • Use the menu system:
     1. Select Terminal > Run Task... from the application menu.
     2. Select Zephyr: Build Application from the drop-down menu.

NOTE: If you see the following message, then you have failed to update the product UID in the sources, and the Notecard will not be linked with your Notehub project.

/workspaces/note-zephyr/src/main.c:26:9: note: '#pragma message: PRODUCT_UID is not defined in this example. Please ensure your Notecard has a product identifier set before running this example or define it in code here. More details at https://bit.ly/product-uid'
   26 | #pragma message "PRODUCT_UID is not defined in this example. Please ensure your Notecard has a product identifier set before running this example or define it in code here. More details at https://bit.ly/product-uid"
      |         ^~~~~~~

Flashing

Linux:

From the Dev Container, use the menu system:

1. Select Terminal > Run Task... from the application menu.
2. Select Zephyr: Flash Application (Container) from the drop-down menu.

Windows/Mac:

1. Launch Debug Server (OpenOCD)

   A debugging server opens a port to receive both debug and program instructions. Then, it forwards those instructions to the target device via a in-circuit debugger and programmer, such as the STLINK-V3MINI.

   Execute the following command on your host machine, OUTSIDE the container:

   openocd --search /usr/share/openocd/scripts --file interface/stlink.cfg --command "transport select hla_swd" --file target/stm32l4x.cfg
   

2. From the Dev Container, use the menu system:

   1. Select Terminal > Run Task... from the application menu.
   2. Select Zephyr: Flash Application (External) from the drop-down menu.

NOTE: You must flash your device using the STLINK-V3MINI; DFU is not supported.

Debugging

Collecting Serial Logs

LPUART has been assigned as the default console output of the Swan. Furthermore, the LPUART of the Swan is exposed via the JTAG connector. This means that all strings provided to printk() will surface through the serial port assigned to the STLINK-V3MINI. As long as the Swan has power (e.g. battery, VIN, etc.), then there is no need for an additional USB cable.

The serial port is configured at 115200 baud, 8-bits, no parity bit, and one (1) stop bit (i.e. 8-N-1).

Using Linux as an example, and assuming the STLINK is the only USB peripheral plugged into your machine. Then you can expect to find the serial port listed as /dev/ttyACM0.

GDB (OpenOCD via STLINK)

Linux:

1. Select the appropriate debug configuation.
   • From the Run and Debug panel.
     1. Open the activity bar using one of the following options:
        • Press the hotkey combination, Ctrl+Shift+D (Mac: Cmd+Shift+D).
        • Select the bug and triangle icon.
     2. Expand the drop-down with the green triangle at the top of the Run and Debug panel.
        • Use the drop-down to confirm Swan Debug (Container) is selected.
2. Launch the debugger using one of the following options:
   • Press green triangle at the top of the Run and Debug panel.
   • Select Run > Start Debugging from the application menu.
   • Press the function key, F5.

Windows/Mac:

1. Launch Debug Server (OpenOCD)

   A debugging server opens a port to receive both debug and program instructions. Then, it forwards those instructions to the target device via a in-circuit debugger and programmer, such as the STLINK-V3MINI.

   Execute the following command on your host machine, OUTSIDE the container:

   openocd --search /usr/share/openocd/scripts --file interface/stlink.cfg --command "transport select hla_swd" --file target/stm32l4x.cfg
   

2. Launch Debugger (GDB)

   A debugger is a piece of software that allows you to step through a binary on a line-by-line basis. When debugging an embedded device, the binary does not reside on the same machine as the debugger, so we need a server (e.g. OpenOCD) to relay the instructions to the remote binary.

   1. Select the appropriate debug configuation.
      • From the Run and Debug panel.
        1. Open the activity bar using one of the following options:
           • Press the hotkey combination, Ctrl+Shift+D (Mac: Cmd+Shift+D).
           • Select the bug and triangle icon.
        2. Expand the drop-down with the green triangle at the top of the Run and Debug panel.
           • Use the drop-down to confirm Swan Debug (External) is selected.
   2. Launch the debugger using one of the following options:
      • Press green triangle at the top of the Run and Debug panel.
      • Select Run > Start Debugging from the application menu.
      • Press the function key, F5.