---
title: Writing Host Firmware with CircuitPython and Blues Swan
description: Build an MCU-controlled application that reads from an external sensor and sends readings to the Notecard to start building your IoT application using Cellular, Satellite, LoRa, or WiFi connectivity.
source_url: https://dev.blues.io/guides-and-tutorials/writing-host-firmware/blues-swan/circuitpython/
canonical_url: https://dev.blues.io/guides-and-tutorials/writing-host-firmware/blues-swan/circuitpython/
markdown_url: https://dev.blues.io/guides-and-tutorials/writing-host-firmware/blues-swan/circuitpython.md
---

# Writing Host Firmware CircuitPython and Blues Swan

In previous tutorials, you used the In-Browser Terminal to communicate with your Notecard and sent hardcoded data to and from the Notehub.

In real-world applications, most connected products are driven by a host: a microcontroller (MCU) or single-board computer (SBC) that reads sensors, runs application logic, and controls the product’s behavior. In Notecard-based projects, the host communicates with Notecard over I2C or UART, typically using one of our official SDKs.

In this tutorial, you’ll learn how to write host firmware that communicates with Notecard, collects data, and sends that data to Notehub.

Versions of this guide are available for several popular languages host platforms. Use the dropdowns below to explore the options. And if you want to communicate with Notecard using a language or environment not covered by this guide, see our [Firmware Libraries](https://dev.blues.io/tools-and-sdks/firmware-libraries.md) page for the official Notecard SDKs for Arduino, C, ESP-IDF, Go, Python, and Zephyr.

*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](https://discuss.blues.com/) 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 **CircuitPython** 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](https://shop.blues.com/collections/swan?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link)

- A Notecard wired to your Blues Swan. If you haven't done this yet, see the [Host Wiring Guide](https://dev.blues.io/guides-and-tutorials/host-wiring-guide.md).

- A Micro USB to USB-A cable

### Software

You'll also need the following software.

- **CircuitPython.** A [CircuitPython bootloader and binary](https://circuitpython.org/downloads) flashed to your Blues Swan, so that it shows up as a `CIRCUITPY` drive. See our guide on [using CircuitPython with the Swan](https://dev.blues.io/feather-mcus/swan/using-circuitpython-with-swan.md).

- **An editor.** A text editor or IDE that works well with CircuitPython, such as [Mu](https://codewith.mu/), [Thonny](https://thonny.org/), or VS Code with the [CircuitPython extension](https://marketplace.visualstudio.com/items?itemName=joedevivo.vscode-circuitpython).

## Create a Notehub Project

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

1. Navigate to [Notehub](https://notehub.io) and log in.

2. Click the **Create Project** button.

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

   ![How to create a new Notehub project](https://dev.blues.io/images/guides/notehub/create-project.png?v=bf29a47a)

   > **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.

   ![Where to find your product UID](https://dev.blues.io/images/guides/notehub/product-uid.png?v=d829ab1d)

## Write Firmware

Now you're ready to write some firmware. When communicating with the Notecard, you can manually send requests using the Serial `write` function and passing-in JSON objects, or use the `note-python` library (the recommended path).

> **Note:**
>
> The rest of this tutorial assumes you have already burned the bootloader and flashed the CircuitPython binary to your MCU.
>
> If you haven't, please [follow our guide on setting up CircuitPython on the Swan](https://dev.blues.io/feather-mcus/swan/using-circuitpython-with-swan.md) before continuing.

### Configure your Notecard

**Install the Notecard Python Library**

1. To use the `note-python` library, you'll first need to download or clone it from the [GitHub repo](https://github.com/blues/note-python).

   ![note-python GitHub download](https://dev.blues.io/images/guides/first-sensor/circuitpython/note-python.png?v=a5abd19a)

2) Unzip the archive and copy the `notecard` directory into the `lib` directory of your `CIRCUITPY` mount.

   ![Copying notecard to CIRCUITPY lib](https://dev.blues.io/images/guides/first-sensor/circuitpython/install-note-python.png?v=02083038)

3. Add an `import` for the library at the top of your `code.py` file.

   ```python
   import notecard
   ```

**Set up Your Notecard**

1. Add some additional imports to the top of your `code.py` file:

   ```python
   import board
   import busio
   import time
   ```

2. Add a definition for your ProductUID using the value you specified when creating your Notehub project.

   ```python
   productUID = "com.your-company.your-name:your_product"
   ```

3. Initialize the connection to your Notecard. Select the tab matching the interface you wired up in the [Host Wiring Guide](https://dev.blues.io/guides-and-tutorials/host-wiring-guide.md).

   **I2C**

   ```python
   port = busio.I2C(board.SCL, board.SDA)
   card = notecard.OpenI2C(port, 0, 0, debug=True)
   ```

   **UART**

   ```python
   serial = busio.UART(board.TX, board.RX, baudrate=9600)
   card = notecard.OpenSerial(serial)
   ```

4. 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.

   ```python
   req = {"req": "hub.set"}
   req["product"] = productUID
   req["mode"] = "continuous"
   rsp = card.Transaction(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 `Transaction` function.

5) Save the `code.py` file to flash this code to your device.

6) Using your IDE or tool of choice, open a Serial monitor to your CircuitPython device. If everything has been connected and configured properly, you'll see a few debug messages, including the JSON object you sent, as well as the response from the Notecard: `{}`.

   ![Notecard hub.set serial output](https://dev.blues.io/images/guides/first-sensor/circuitpython/nc-configured-lib.png?v=eae465f5)

### Read from the Sensor

Now that you've configured your MCU to communicate with the Notecard, let's grab some pseudo sensor readings, where the `temperature` comes from the onboard temperature sensor of the Notecard and the `humidity` is a random number.

> **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.

1. To generate pseudo sensor readings you'll use the `notecard-pseudo-sensor` library. Start by downloading or cloning the library from [its GitHub repo](https://github.com/blues/notecard-pseudo-sensor-python).

   ![The location of the download button in GitHub](https://dev.blues.io/images/guides/first-sensor/circuitpython/sensor-github-download.png?v=489d7514)

2) Next, unzip the archive and copy the `notecard_pseudo_sensor` directory into the `lib` directory of the `CIRCUITPY` mount.

   ![How to move the sensor library to the device](https://dev.blues.io/images/guides/first-sensor/circuitpython/sensor-library-move.png?v=0c343248)

3. Add an import for the library at the top of your `code.py` file.

   ```python
   import notecard_pseudo_sensor
   ```

4. Configure the pseudo sensor with a reference to the Notecard you created earlier.

   ```python
   sensor = notecard_pseudo_sensor.NotecardPseudoSensor(card)
   ```

5. Add the following code block to the bottom of your `code.py` file. This takes a mock temperature and humidity reading before sleeping for 15 seconds and repeating the process.

   ```python
   while True:
      temp = sensor.temp()
      humidity = sensor.humidity()
      print("\nTemperature: %0.1f C" % temp)
      print("Humidity: %0.1f %%" % humidity)

      time.sleep(15)
   ```

6) Save `code.py` and reopen the Serial monitor. Every 15 seconds, you'll see new readings.

   ![CircuitPython sensor readings output](https://dev.blues.io/images/guides/first-sensor/circuitpython/sensors-readings.png?v=5babd92e)

### Send Sensor Readings to the Notecard

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

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 the `while` loop right after the `print` commands used to print out readings.

   ```python
   req = {"req": "note.add"}
   req["file"] = "sensors.qo"
   req["sync"] = True
   req["body"] = { "temp": temp, "humidity": humidity}
   rsp = card.Transaction(req)
   print(rsp)
   ```

2) Save this code to your device. After restart, 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.

   ![CircuitPython note totals output](https://dev.blues.io/images/guides/first-sensor/circuitpython/notes-lib.png?v=c83957d7)

## 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](https://notehub.io) and open your project. You should see your Notecard in the Devices view.

   ![The new device in Notehub](https://dev.blues.io/images/guides/notehub/new-device.png?v=f506b425)

   > **Note:**
   >
   > Each Notecard has a factory-assigned, globally unique identifier known as a [DeviceUID](https://dev.blues.io/api-reference/glossary.md#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](https://dev.blues.io/api-reference/glossary.md#product-sn) 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](https://dev.blues.io/api-reference/notehub-api/device-api.md#set-device-environment-variables) endpoint.
   > - **Via the Notecard API**: Include an `sn` argument in the [hub.set request](https://dev.blues.io/api-reference/notecard-api/hub-requests/latest.md#hub-set) 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.

   ![The event list in Notehub](https://dev.blues.io/images/guides/notehub/events.png?v=76323245)

## Use Environment Variables

[Environment variables](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables.md) 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](https://dev.blues.io/api-reference/notecard-api/env-requests.md). The most common of these requests is [`env.get`](https://dev.blues.io/api-reference/notecard-api/env-requests.md#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:**
>
> **Prompt:**
>
> ```text
> 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. First, 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.

   ```python
   req = {"req": "hub.set"}
   req["product"] = productUID
   req["mode"] = "continuous"
   req["inbound"] = 5 # add this line
   rsp = card.Transaction(req)
   ```

2. Next, place the following new function before the existing `while True` loop.

   ```python
   # 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.
   def get_sensor_interval():
      sensor_interval_seconds = 60
      req = {"req": "env.get"}
      req["name"] = "reading_interval"
      rsp = card.Transaction(req)
      try:
         reading_interval = int(rsp.get("text", ""))
         if reading_interval > 0:
            sensor_interval_seconds = reading_interval
      except (AttributeError, TypeError, ValueError):
         pass
      return sensor_interval_seconds
   ```

3. Finally, find the existing `time.sleep(15)` line in your `while True` loop, and replace it with the code below.

   ```python
   sensor_interval_seconds = get_sensor_interval()
   print(f"Delaying {sensor_interval_seconds} seconds")
   time.sleep(sensor_interval_seconds)
   ```

   > **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 alongside your other Notecard configuration (before your `while True` loop) to provide a template for the `reading_interval` variable.
   >
   > ```python
   > req = {"req": "env.template"}
   > req["body"] = {"reading_interval": 21}
   > card.Transaction(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.

Your firmware now uses the `reading_interval` environment variable to determine how many seconds to delay in between sensor readings.

If you save this code, after restart you should see your device using the default `reading_interval` value 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](https://dev.blues.io/api-reference/notehub-api/project-api.md).

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.

   ![The Notehub device screen](https://dev.blues.io/images/guides/first-sensor/environment/device-screen.png?v=cdb91b6c)

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`.

   ![The environment screen with a new value set](https://dev.blues.io/images/guides/first-sensor/environment/setting-a-variable.png?v=e576ef35)

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

![The environment screen with a new value set](https://dev.blues.io/images/guides/first-sensor/environment/env-var-serial-log-circuitpython.png?v=119a9abd)

> **Note:**
>
> On cellular and WiFi-based Notecards you can use the [`hub.set` request](https://dev.blues.io/api-reference/notecard-api/hub-requests/latest.md#hub-set)'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.

```json
{
  "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.

```json
{
  "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](https://www.youtube.com/watch?v=3D2p1t8UMHQ). 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](https://dev.blues.io/notecard/notecard-walkthrough/low-power-firmware-design.md).

> **AI Tip:**
>
> LLMs can also help you get your configuration right.
>
> **Prompt:**
>
> ```text
> 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](https://dev.blues.io/guides-and-tutorials/routing-data-to-cloud.md)

At any time, if you find yourself stuck, please reach out on the [community forum](https://discuss.blues.com/).