Writing Host Firmware
- C/C++ (Arduino) and Blues Swan

Don't see your favorite hardware here? Rest assured the Notecard works with virtually every MCU and SBC available. If you can't figure out how to complete this tutorial let us know in our forum and we can help you out.

Introduction

This tutorial should take approximately 40-50 minutes to complete.

In this tutorial, you'll learn how to use C/C++ (Arduino) to write firmware that runs on a Blues Swan.. Specifically, your firmware will collect temperature and humidity data at an interval, queue it on your Notecard, and synchronize it to Blues Notehub.

This tutorial uses a library that provides mock sensor readings for simplicity, but feel free to hook up a physical sensor of your choice and use that instead. The goal of this tutorial is to demonstrate reusable firmware techniques you can apply to your own Notecard-based projects.

AI Tip

Throughout this guide we’ll share tips for writing host firmware with AI, which we recommend. Look for these boxes for AI-specific guidance and prompts you can use with your LLM of choice.

Setup

Make sure you've met the following hardware and software requirements before continuing.

Hardware

To complete this guide, you'll need the following hardware.

• A Blues Swan

• A Notecard wired to your Blues Swan. If you haven't done this yet, see the Host Wiring Guide.

• A Micro USB to USB-A cable

• Optionally, an STLINK-V3MINI programmer. You can flash firmware over USB alone, but an STLink removes the need to enter bootloader mode before every upload and enables step debugging.

Software

You'll also need the following software.

• An IDE. You can complete this guide using either Arduino IDE (recommended) or PlatformIO. If you don’t have one of these IDEs set up already, complete one of the following guides.
  • Arduino IDE: Swan quickstart
  • PlatformIO: Using PlatformIO with Swan

AI Tip

When writing host firmware with AI, we recommend installing Blues Expert MCP. Blues Expert connects your AI coding assistant—Claude Code, GitHub Copilot, Cursor, etc—directly to our API docs, providing live request validation and firmware best practices for Arduino, C, Zephyr, and Python.

Promptcontent_copyCopy

Add a new HTTP MCP server named Blues Expert using https://mcp.blues.io/expert/mcp.

Create a Notehub Project

Now that your hardware is ready, let's create a new Notehub project for this tutorial.

1. Navigate to Notehub and log in.

2. Click the Create Project button.

3. In the New Project dialog, give your project a name and ProductUID.

   

   note

   The ProductUID must be globally unique, so we recommend a namespaced name like "com.your-company.your-name:your_product".

4. Take note of your ProductUID. This identifier is used by Notehub to associate your Notecard with your project.

   

Write Firmware

For this portion of the guide you'll be writing firmware on your Blues Swan that will communicate with the Notecard. You can write the firmware using either Arduino IDE (recommended) or PlatformIO.

Communicating With Your Notecard

When communicating with the Notecard, the easiest approach is to use one of Notecard's official SDKs. Since this tutorial uses Arduino, let's install the Arduino SDK, note-arduino.

Install the Notecard Arduino Library

Set Up Your Notecard

With the Notecard’s Arduino SDK installed, let’s start writing firmware. The steps below show you how to initialize a Notecard in an Arduino sketch, using AI or writing code manually.

AI Tip

Now that your project is set up and the necessary dependencies are installed, you’re ready to use an LLM to generate your host firmware.

To start, we recommend opening your AI coding assistant in the same folder as your firmware project. At a minimum, make sure your LLM knows where your code is located so it can make updates.

• Arduino IDE
  • Windows: C:\Users\<username>\Documents\Arduino\project_name
  • macOS: ~/Documents/Arduino/project_name
  • Linux: ~/Arduino/project_name
• PlatformIO
  • Windows: C:\Users\<username>\Documents\PlatformIO\Projects\project_name
  • macOS: ~/Documents/PlatformIO/Projects/project_name
  • Linux: ~/Documents/PlatformIO/Projects/project_name

Next, create an AGENTS.md file to provide the LLM context about the project you’re building. List all the hardware you’re using in this file, as well as a description of what your project does.

Promptcontent_copyCopy

Create an AGENTS.md file for this host firmware project. Record that I’m using a Notecard and a Blues Swan, and that I’m building a project that takes regular temperature and humidity readings.

Finally, we recommend using the tools in Blues Expert MCP to scaffold the initial version of your project.

Promptcontent_copyCopy

Use Blues Expert to scaffold this sketch as a Notecard project. Put my Notecard in continuous mode, and prompt me for my Notehub project’s ProductUID. Leave the loop empty for now; I want to make sure my Notecard initializes correctly first.

And if you’re not using AI (or you just want some background on how things work), the steps below show how to set up your Notecard in host firmware with manually written code.

If you’re unsure whether you’re using I2C or UART, see our Host Wiring Guide. Notecarrier CX and F boards connect the host to Notecard over I2C by default, so if you're using either of those, you're on I2C.

6. Now, we'll configure the Notecard. Using the hub.set request, we associate this Notecard with the ProductUID of your project and set the Notecard to operate in continuous mode, which indicates that the device should immediately make a connection to Notehub and keep it active.

   COPY

   {
     J *req = notecard.newRequest("hub.set");
     if (req != NULL) {
       JAddStringToObject(req, "product", productUID);
       JAddStringToObject(req, "mode", "continuous");
       notecard.sendRequest(req);
     }
   }

   The lines above build up a JSON object by adding two string values for product and mode, and then fire the request off to the Notecard with the sendRequest() function.

Flash Your Firmware

1. If you're NOT using an STLink programmer like the STLINK-V3MINI, you'll need to put your Blues Swan into bootloader mode before every upload, including this one. To do so, press and hold the BOOT button, press and release the reset button (labeled RST on the Notecarrier CX and RESET on the Cygnet and Swan), then release BOOT.

   Arduino IDE

   If you're using Arduino IDE, click the Upload button (right arrow icon) to flash the firmware to your device.

   

   PlatformIO

   If you're using PlatformIO, click the Upload button (right arrow icon) at the bottom of the VS Code interface to flash the firmware to your device.

   

View the Serial Log

Now that your firmware is running on your device, you can use a Serial Monitor to view device output. If you are using an STLINK programmer, you will need to connect a second USB cable from your computer directly to your STM32-based host to view serial output.

Complete the instructions below in your preferred IDE.

Read From the Sensor

Now that you've configured your host to communicate with your Notecard, let's next look at how to take some mock sensor readings.

note

If you have your own sensor, feel free to hook it up and use your own values instead of this tutorial's mocked ones.

Install the NotecardPseudoSensor Library

To generate mock sensor readings we'll use the NotecardPseudoSensor library.

Complete the instructions below for your preferred IDE.

Gather Sensor Readings

Use the instructions below to take sensor readings in firmware using AI or writing code manually.

AI Tip

The prompt below can be used to generate firmware that uses the NotecardPseudoSensor library. If you’re using your own sensor, add it to your AGENTS.md file (ideally with a link to its datasheet!) before asking your LLM to generate firmware that uses it.

Promptcontent_copyCopy

Take a temperature and humidity reading using the NotecardPseudoSensor library every 15 seconds. Make 15 seconds a configurable interval. Log the values from the sensor to the serial log.

1. Add the following include to the top of your sketch:

   COPY

   #include <NotecardPseudoSensor.h>

2. Next, include the following namespace under your includes.

   COPY

   using namespace blues;

3. After that, create an instance of NotecardPseudoSensor with the line of code below. Place this directly under your existing Notecard notecard statement.

   COPY

   NotecardPseudoSensor sensor(notecard);

4. Finally, place the following code in your loop function, which generates mock temperature and humidity readings, prints them to the console, and then waits 15 seconds before the loop runs again.

   COPY

   float temperature = sensor.temp();
   float humidity = sensor.humidity();
   
   usbSerial.print("Temperature = ");
   usbSerial.print(temperature);
   usbSerial.println(" *C");
   usbSerial.print("Humidity = ");
   usbSerial.print(humidity);
   usbSerial.println(" %");
   
   delay(15000);

5. Upload this code to your Blues Swan. Open the Serial Monitor and you'll see temperature and humidity readings every 15 seconds.

   

Send Sensor Readings to the Notecard

Now that we're getting sensor readings, let's send these to our Notecard.

AI Tip

Promptcontent_copyCopy

Queue each temperature and humidity reading from the sensor library in a Note on my sensors.qo Notefile. Use sync: true on the note.add to trigger an immediate Notehub sync.

1. To send a sensor reading to the Notecard, we'll need to construct a new JSON request to the note.add API that includes a new Notefile name (sensors.qo), sets the sync field to true to instruct the Notecard to sync to Notehub immediately, and finally, sets the body to the sensor temperature and humidity. Add the following in loop right after the usbSerial commands to print out readings.

   COPY

   {
     J *req = notecard.newRequest("note.add");
     if (req != NULL) {
       JAddStringToObject(req, "file", "sensors.qo");
       JAddBoolToObject(req, "sync", true);
       J *body = JAddObjectToObject(req, "body");
       if (body) {
         JAddNumberToObject(body, "temp", temperature);
         JAddNumberToObject(body, "humidity", humidity);
       }
       notecard.sendRequest(req);
     }
   }

2. Upload this code to your device, entering bootloader mode again first if you're not using an STLink programmer. After reboot, the Serial monitor will update to display the response from the note.add request (the total number of Notes in the Notefile) each time you add a new reading.

   

note

If you're using a Notecard for LoRa to complete this tutorial you have one additional step. Because the Notecard for LoRa requires a template for every Notefile you use, you must define a template for the sensors.qo Notefile in your setup() function. You can add the following code to the bottom of your setup() function to fix the problem.

COPY

{
  J *req = notecard.newRequest("note.template");
  if (req != NULL) {
    JAddStringToObject(req, "file", "sensors.qo");
    JAddNumberToObject(req, "port", 1);
    JAddStringToObject(req, "format", "compact");
    J *body = JCreateObject();
    if (body != NULL) {
      JAddNumberToObject(body, "temp", 14.1);
      JAddNumberToObject(body, "humidity", 14.1);
      JAddItemToObject(req, "body", body);
      notecard.sendRequest(req);
    }
  }
}

Learn more about Notefile templates in Working with Note Templates.

note

Concerned about the size of note-arduino? You can communicate with the Notecard without using the library.

View Data in Notehub

Once you start capturing readings, your Notecard will initiate a connection to Notehub and will start transferring Notes. Depending on signal strength and coverage in your area, it may take a few minutes for your Notecard to connect to Notehub and transfer data.

1. Return to Notehub and open your project. You should see your Notecard in the Devices view.

   

   note

   Each Notecard has a factory-assigned, globally unique identifier known as a DeviceUID. Notehub uses this identifier in the Devices view by default (for example, dev:868531061604976 in the screenshot above).

   If you’d prefer to use your own identifier—such as a human-readable name or an internal ID—you can assign a serial number to your Notecard in one of the following ways:

   • In Notehub: Double-click your device in the Devices view to open its details, where you can edit the serial number.
   • Via the Notehub API: Set the reserved _sn environment variable using the Set Device Environment Variables endpoint.
   • Via the Notecard API: Include an sn argument in the hub.set request you used to configure your Notecard.

2. Now, click on the Events left menu item. Once your sensor Notes start syncing, they'll show up here. You may need to refresh the page to see newly synced Notes.

   

Use Environment Variables

Environment variables are a Notehub state and settings management feature that allow you to set variables in key-value pairs, and intelligently synchronize those values across devices and fleets of devices.

In this section you'll learn how environment variables work by creating a variable that determines how often your firmware should take sensor readings.

Using Environment Variables in Firmware

The Notecard provides a set of requests for working with environment variables. The most common of these requests is env.get, which allows you to retrieve the value of an environment variable.

Complete the steps below to use the env.get request to retrieve and use the reading_interval environment variable.

AI Tip

Promptcontent_copyCopy

Set my Notecard to use an inbound interval of 5 minutes. Read a new environment variable named reading_interval, and use that to determine how many seconds the firmware should wait between sensor readings.

1. In setup(), adjust your existing hub.set configuration to set the inbound argument to 5. This tells your Notecard to look for inbound changes from Notehub every 5 minutes.

   COPY

   {
     J *req = notecard.newRequest("hub.set");
     if (req != NULL) {
       JAddStringToObject(req, "product", productUID);
       JAddStringToObject(req, "mode", "continuous");
       JAddNumberToObject(req, "inbound", 5); // ADD THIS LINE
       notecard.sendRequest(req);
     }
   }

2. Next, place the following new function at the bottom of your sketch.

   COPY

   // This function assumes you’ll set the reading_interval environment variable to
   // a positive integer. If the variable is not set, set to 0, or set to an invalid
   // type, this function returns a default value of 60.
   int getSensorInterval() {
     int sensorIntervalSeconds = 60;
     J *req = notecard.newRequest("env.get");
     if (req != NULL) {
       JAddStringToObject(req, "name", "reading_interval");
       J* rsp = notecard.requestAndResponse(req);
       int readingIntervalEnvVar = atoi(JGetString(rsp, "text"));
       if (readingIntervalEnvVar > 0) {
         sensorIntervalSeconds = readingIntervalEnvVar;
       }
       notecard.deleteResponse(rsp);
     }
     return sensorIntervalSeconds;
   }

3. Then, add this line after the #include lines at the top of the file.

   COPY

   int getSensorInterval();

4. Next, find the delay(15000) line at the bottom of your loop() function, and replace it with the code below.

   COPY

   int sensorIntervalSeconds = getSensorInterval();
   usbSerial.print("Delaying ");
   usbSerial.print(sensorIntervalSeconds);
   usbSerial.println(" seconds");
   delay(sensorIntervalSeconds * 1000);

   note

   Notecard for LoRa requires a template for each environment variable you use. If you're using a Notecard for LoRa to complete this tutorial, add the code below to your setup() to provide a template for the reading_interval variable.

   COPY

   {
     J *req = notecard.newRequest("env.template");
     if (req != NULL) {
       J *body = JCreateObject();
       if (body != NULL) {
         JAddNumberToObject(body, "reading_interval", 21);
         JAddItemToObject(req, "body", body);
         notecard.sendRequest(req);
       }
     }
   }

   Here 21 is the type hint for a 1-byte unsigned integer (0–255). If your reading_interval may exceed 255, use 22 (a 2-byte unsigned integer) instead.

With this code in place, your firmware now uses the reading_interval environment variable to determine how many seconds to delay in between sensor readings. If you flash this updated code to your device and open your serial monitor, you can see the device using the default value for reading_interval of 60 seconds.

Setting an Environment Variable

Now that we have our device programmed to retrieve an environment variable from Notehub, we will create that variable. Environment variables can be set in the Notehub UI or through the Notehub API. In this tutorial you'll learn how to set the values through the Notehub UI. If you'd like to instead set environment variables through the Notehub API, refer to environment variable requests in the Project API.

1. Return to your Notehub project, go to the Devices page, and double-click your device. You should see a screen that looks like this.

   

2. Click the Environment tab.

3. Under the Device environment variables header, define a new environment variable named reading_interval and set its value to 30.

   

Now that you have an environment variable set, you'll see it reflected on your device after your configured inbound interval has passed.

note

On cellular and WiFi-based Notecards you can use the hub.set request's sync argument to immediately receive inbound updates instead of relying on the inbound interval.

And with that, you've used your first environment variable on your Notecard! To see the real power of environment variables in action, try returning to Notehub and updating your device's reading_interval with your serial monitor open.

Update Your hub.set Configuration

Throughout this tutorial, you've used several configuration settings that are typically only appropriate for a Notecard running on mains power.

• In the hub.set request, setting mode to "continuous" tells the Notecard to maintain an active network connection.

• In the note.add request, setting sync to true tells the Notecard to immediately synchronize all outbound Notes to Notehub.

Because each of these settings causes the Notecard to use more power, you may wish to disable them if you plan to transition your project to battery power. The requests below show a more typical setup for a battery-powered Notecard.

Start with hub.set. Setting mode to "periodic" tells the Notecard to connect on a schedule rather than holding a connection open, and the outbound and inbound intervals control how many minutes it waits before syncing in each direction.

{
  "req": "hub.set",
  "mode": "periodic",
  "outbound": 60,
  "inbound": 360
}

Then set sync to false on your note.add requests, so each reading waits for the next scheduled sync instead of triggering one of its own.

{
  "req": "note.add",
  "file": "sensors.qo",
  "sync": false,
  "body": { "temp": 22.5, "humidity": 41.2 }
}

tip

• For a deeper look at how the hub.set request’s settings work together, watch An In-Depth Guide to Notecard’s hub.set Request. The video steps through complete configuration scenarios that show how your choice of mode, outbound, inbound, and sync values determines exactly when your Notecard connects and syncs with Notehub.

• For other recommendations when building low-power friendly firmware, see Low-Power Firmware Design.

AI Tip

LLMs can also help you get your configuration right.

Promptcontent_copyCopy

Review the Blues recommendations for the hub.set request at https://dev.blues.io/notecard/notecard-walkthrough/essential-requests/#notehub-configuration-hub-set. Then help me get my own hub.set configuration right in my firmware based on what you know about my project. Ask me questions to gather more information as necessary.

Next Steps

Congratulations! You've successfully connected your Blues Swan to your Notecard and built a basic IoT project.

If you're following a Cell+WiFi Quickstart, next we recommend learning how to send (and visualize) your data in a cloud application:

1. Use the Notecard to Send Data
2. Host Wiring Guide
3. Build Your First IoT App With Blues
4. Send Data to Your Cloud

At any time, if you find yourself stuck, please reach out on the community forum.