--- title: Zephyr Library description: A guide for installing and using the Notecard Zephyr library, known as note-zephyr. source_url: https://dev.blues.io/tools-and-sdks/firmware-libraries/zephyr-library/ canonical_url: https://dev.blues.io/tools-and-sdks/firmware-libraries/zephyr-library/ markdown_url: https://dev.blues.io/tools-and-sdks/firmware-libraries/zephyr-library.md --- # Zephyr Library [note-zephyr](https://github.com/blues/note-zephyr) is the official Zephyr library for communicating with the Notecard over serial or I2C, packaged as a [west](https://docs.zephyrproject.org/latest/guides/west/index.html) module. In this article, you'll learn how to use `note-zephyr` to upgrade the Zephyr RTOS "blinky" example with [Notecard](https://shop.blues.com/collections/notecard?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) communication! ## Overview This example is designed to illustrate the ease of adding Notecard functionality to an existing application, by building on the original Zephyr sample, `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 Notecard](https://shop.blues.com/collections/notecard?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) - [Blues Notecarrier](https://shop.blues.com/collections/notecarrier?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) - [Blues Swan](https://shop.blues.com/collections/swan?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) - [STLINK Programmer/Debugger](https://shop.blues.com/collections/accessories/products/stlink-v3mini?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) ### Software - [Docker](https://docs.docker.com/get-docker/) - [Visual Studio Code (VS Code)](https://code.visualstudio.com/Download) - [VS Code "Dev Containers" Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) - **Windows/Mac Debugging** [OpenOCD](https://openocd.org/pages/getting-openocd.html) ### Cloudware - [Notehub.io](https://notehub.io) ## Getting Set Up ### Notehub.io Before you can utilize this example, you must set up a free account (no credit card required) on [Notehub.io](https://notehub.io). Once you have created your account, then you need to [create a project](https://dev.blues.io/quickstart/notecard-quickstart/notecard-simulator.md#create-a-notehub-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](https://dev.blues.io/notehub/notehub-walkthrough.md#finding-a-productuid). 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. To learn more about the Notecard modes and API, please visit our [Essential Requests Walkthrough](https://dev.blues.io/notecard/notecard-walkthrough/essential-requests.md#configuring-synchronization-modes). ### Cloning the Repository This repository contains the `note-c` library as a submodule. Use the following command to clone both repositories simultaneously. ```plaintext 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: ```plaintext 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: ```json // 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:** Ensure Docker Desktop is running. > **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. > > ```unknown > docker system prune > ``` > > ```unknown > 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 VS Code. 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. 3. When prompted, type *examples/blinky* and press enter. > **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. > > ```plaintext > /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 Firmware (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 an in-circuit debugger and programmer, such as the STLINK-V3MINI. Execute the following command on your host machine, *OUTSIDE* the container: ```plaintext 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 Firmware (External)** from the drop-down menu. > **Note:** > > You must flash your device using the [STLINK-V3MINI](https://shop.blues.com/products/stlink-v3mini?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link); 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](https://en.wikipedia.org/wiki/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 an in-circuit debugger and programmer, such as the STLINK-V3MINI. Execute the following command on your host machine, *OUTSIDE* the container: ```plaintext 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`. ## Update Existing Zephyr App Below are the minimum changes required to add the Notecard functionality to a pre-existing Zephyr application. 1. Add the `note-zephyr` module to your application manifest. Below is an example of a `west.yml` file that adds the `note-zephyr` module to the application. ```unknown manifest: projects: - name: zephyr revision: main url: https://github.com/zephyrproject-rtos/zephyr import: name-allowlist: - hal_stm32 - cmsis - name: note-zephyr path: modules/note-zephyr revision: main submodules: true url: https://github.com/blues/note-zephyr # your other modules here ... ``` > **Note:** > > It is **required** that `submodules: true` is present in the module's `west.yml` entry, as it depends on [`note-c`](https://github.com/blues/note-c). 2. Run `west update` to fetch the `note-zephyr` module. 3. In your application's `prj.conf` file, add the following: ```unknown # Required by `note-c` CONFIG_NEWLIB_LIBC=y CONFIG_BLUES_NOTECARD=y # Optional: Enable logging CONFIG_BLUES_NOTECARD_LOGGING=y ``` 4. You'll then need to ensure that your application's target device can communicate with the Notecard. This is done by adding the appropriate device tree overlay to your target. ### I2C - overlay for a Feather MCU connected to a Notecarrier-F ```unknown &feather_i2c { status = "okay"; notecard@17 { compatible = "blues,notecard"; reg = <0x17>; status = "okay"; }; }; ``` ### Serial (UART) - overlay for a Feather MCU connected to a Notecarrier-F ```unknown &feather_serial { status = "okay"; current-speed = <115200>; notecard { compatible = "blues,notecard"; status = "okay"; }; }; ``` > **Note:** > > UART is not physically connected between the Notecard and the feather MCU, when using the [Notecarrier-F](https://blues.com/products/notecarrier/notecarrier-f). In order to use UART (serial), the following steps are required: > > - Set DFU switch to OFF, to isolate `AUX_TX`/`AUX_RX` from `F_RX`/`F_TX`, respectively. > > - Connect the following lines together with a jumper wire: > > - `N_TX` to `F_RX`. > - `N_RX` to `F_TX`. 5. Build and flash your application as usual. E.g. `west build -b swan_r5 your_application && west flash` And with that, you're all set up and ready to utilize the Notecard in your existing Zephyr application. ## Links - [The Zephyr Project](https://www.zephyrproject.org/) - [GitHub: `note-zephyr`](https://github.com/blues/note-zephyr)