Page Comparison

The Sparrow family consists of one or more Sensors which communicate JSON-formatted Notes using a LoRa radio to a Gateway with which they have been manually paired. A Sparrow Gateway will forward messages received from its paired Sensors to the cloud via Notecard. Conversely, it will also forward messages received from the cloud via Notecard to an associated Sensor.

The goal of this guide is to provide everything you need to help you set up, configure and start collecting data from the Sparrow platform!

Prerequisites

Hardware

Sparrow Essentials Board
Sparrow Reference Sensor Board
Notecard (preferably Note-WiFi)
Notecarrier-AL (with Qwiic Connector)
STLINK-V3MINI
Qwiic Cable
USB Type A-to-Micro Cable
LiPo (2000mAh)
(2x) AAA Batteries

Software

Firmware

Sparrow Accelerator Sensor Firmware (clone using --recursive)

Tooling

Native Installation
- CMake (must be v3.14 or greater)
- Make
- ST-LINK GDB Server (via STMCubeIDE)
- STM32CubeProg
- VSCode “Cortex-Debug” Extension
- VSCode “Cortex-Debug: Device Support Pack - STM32WL” Extension
- Terminal Program (choose one)
  - [MacOS] CoolTerm
  - [Linux] GTKTerm
  - [Windows] PuTTY
  - Arduino Serial Montior (Arduino IDE)
- [OPTIONAL] GNU ARM toolchain (also packaged with STM32CubeIDE)

NOTE: Be sure to add/install all tools/libraries into your system path.
This may be necessary of all tools, but is especially important for ST-LINK_gdbserver and its shared library dependency, libSTLinkUSBDriver.so (or platform specific equivalent).
Linux:

Code Block

language	none

export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.linux64_2.0.0.202105311346/tools/bin:${PATH}
export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.linux64_2.0.100.202110141430/tools/bin:${PATH}
export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin:${PATH}
export LD_LIBRARY_PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/native/linux_x64:${LD_LIBRARY_PATH}

Mac OS (set in your ~/.bashrc file or whatever terminal you prefer):

Code Block

language	none

export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.macos64_2.0.0.202105311346/tools/bin:$PATH"export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.macos64_2.0.0.202105311346/tools/bin:$PATH"
export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.macos64_2.0.100.202110141430/tools/bin:$PATH"
export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_2.0.100.2109301221/tools/bin:$PATH”
export DYLD_LIBRARY_PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_2.0.100.202109301221/tools/bin/native/mac_x64:$DYLD_LIBRARY_PATH”

[LINUX ONLY] Containerized Development Environment
- Docker
- VSCode “Remote - Containers” Extension

Understanding the Hardware

At its core the Sparrow is a single piece of hardware, which comes in one of three configurations:

Sparrow Core Board
The most basic configuration, it comes completely depopulated. It is the theoretical starting point for someone to take the hardware, prototype with their own sensors, and then make their own PCB based on our design.
Sparrow Essentials Board
Designed for rapid prototyping, it comes populated with the following items:
- Cortex Debug Connector
- Female Pin Headers
- RESET/BOOT Buttons
- LiPo JST Connector
- Qwiic Connector
- Coin-cell Battery Holder
Sparrow Reference Sensor Board
Just add batteries and go. The reference sensor board comes with an integrated BME280 and PIR sensor. Once this device has been paired with a Gateway, then this device will start automatically capturing real data that you can work with while configuring your Notehub project.
It comes populated with the following items:
- Bosch BME280 (temp/humidity/pressure) Sensor
- PIR (motion) Sensor
- Cortex Debug Connector
- RESET/BOOT Buttons
- (2x) AAA Battery Holder

Unified Firmware, Split Personality

All the different Sparrow configurations run off the same firmware. Once the firmware boots, it looks for a Notecard (of any flavor) on the I2C bus. If it finds one, then it decides that it is an Essentials Board which is wired up as part of a Sparrow Gateway. If not, it then looks for a BME280 environmental sensor on the I2C bus. If it finds one, then it decides it is a Reference Sensor Board. However, if it finds neither, then it defaults to behaving as a Core Board.

Hardware Setup

Sparrow Gateway

Construction

On boot, the Sparrow firmware will begin looking for a Notecard on its I2C bus. If it discovers one, then it will assume the “Gateway” personality.

To construct a Sparrow Gateway, connect your Sparrow Essentials Board to your Notecarrier using the Qwiic cable and Qwiic connectors.

You must connect the LiPo battery to the JST connector on Notecarrier, and not the JST connector on the Sparrow.
Notecarrier DIP switch must be set to 3V3, instead of 1V8.
Oh no, my hardware doesn’t have a Qwiic Connector!?!
Pin Mapping Table

...

Notecarrier

...

Sparrow Gateway

...

Qwiic Color

...

<VIO

...

<VIO

...

RED

...

GND

...

GND

...

BLACK

...

SCL

...

SCL

...

YELLOW

...

SDA

...

SDA

...

BLUE

NOTE: If you have a Qwiic connector breakout, you can connect to the Qwiic connector of the Sparrow, and the same pins on the Notecarrier as above.

Connect to Notehub

If you are using a Wi-Fi Notecard, be sure to connect to your local network.

Code Block
{"req":"card.wifi","ssid":"<ssid name>","password":"<password>"}

There are two ways to connect your project to Notehub (choose one):

Configure the Notecard to connect to your Notehub product directly over USB (as you normally would).
Code Block
{"req":"hub.set","product":"<your_product_id>"}
Update the NOTECARD_PRODUCT_UID variable in sparrow-lora/Application/config_notecard.h to force your Sparrow Applications to connect to the desired Notehub product.

NOTE: If neither your Notecard nor the settings file are configured, then the Gateway will prompt you to configure the Notecard using a hub.set request.

WARNING: The dip switch on the Notecarrier-AL MUST be set to 3V3 when using a Wi-Fi Notecard.

Sparrow “Application Host” Node

Once the Sparrow firmware has decided it is NOT the “Gateway” personality, then it will assume the “Application Host” personality. A one-time pairing must be performed between every Application Host and Gateway. After being successfully pairing the Sparrow Sensor Reference Board, the BME280 and PIR sensors will be automatically detected by the firmware, and the device will begin to capture and report data to Notehub without any further configuration.

Manual Configuration of a Sparrow Node Details
Use the MAC of the Sparrow node as the Note ID, and update the following fields:
- name - A friendly name for the device
- loc - The location of the Sparrow Node
  NOTE: By convention, the loc field should be the GPS coordinates of the Node in OLC format (more info)

Example:
{"req":"note.update","file":"config.db","note":"20323746323650050042000b","body":{"name":"Office","loc":"8624G9CM+XM"}}

Radio Frequency

The Sparrow uses the LoRa protocol, and operates on the ISM (industrial, scientific, medical) band. Unfortunately, the ISM band is not standardized globally, so the frequency of the Sparrow must be set to operate the region in which it is being used. There are a set of DIP switches on the Sparrow, which allow you to easily select the transmission band.

WARNING: For legal use in the US and Canada, the Sparrow DIP switches MUST be set to the OFF position on all boards.

Pairing

Pairing requires a Sparrow Gateway and a Sparrow Node. This means each Sparrow device must have assumed the correct personality. This is a requirement, because the Gateway is responsible for storing the encryption keys and topology related to the hub and spoke network.

Pairing is straight-forward and easy to do, just follow the pairing instructions below.

Sparrow Usage/Operation

Understanding Hardware Behaviors

Button Behaviors

PAIR
- Held at Boot - Enable tracing logs over debug UART.
- Press
  - gateway - Enter pairing mode.
  - leaf-node
    - unpaired - Enter pairing mode.
    - paired - Send test message to gateway.
- Press & Hold - Enable "soft access point" on attached Note Wi-Fi.
  Press & Hold (30 seconds) - Reset to factory settings.
RESET - Press to reset device
BOOT - Press to enter bootloader mode (DFU)

LED Behaviors

Blue (PAIR) - Pairing mode.
- The Gateway will accept incoming requests
- A Node will be pinging, searching for a Gateway.
Green (RX) - Receive mode, waiting for an application to send it data.
Red (TX) - Transmit mode, actively sending data.
Blue & Green - Scanning for gateway (red will blink with each ping).
Red & Green - Attempting to send, but waiting for clear air (i.e. listening before speaking).
Red & Green & Blue
- steady on - booting.
- crawling
  - on start up - Gateway is connecting to Notehub.
  - on PAIR button hold - SoftAP is active.
- flash - Last operation acknowledgment.
  3 flashes - Factory reset has completed.

Pairing a Sensor to the Gateway

Press PAIR on the Sparrow Node
Press PAIR on the Sparrow Gateway

Pairing the devices is easiest when they are separated from each other (opposite sides of the table should be fine). Once the PAIR button has been pressed, the LED lights will begin to crawl until the devices have been paired. Once the devices have paired, the lights will flash to acknowledge success.

Building/Flashing/Debugging the Firmware

STM32CubeIDE

Load the project into your workspace

...

Open the STM32CubeIDE application.
Navigate to File > Open Projects from File System....
Press the Directory... button.
Open the hidden folder, .STM32CubeIDE, from the newly cloned repository.
Press the Finish button.

Update Build Defines

NOTE: If you have the v1.1 hardware then you may skip this section...

Right-click on the project, sparrow (in .STM32CubeIDE) and select Properties.
Unfold the C/C++ General menu.
Select Paths and Symbols.
Select the # Symbols tab.
Select “GNU C” from the Languages column
Click Add....
Enter “CURRENT_BOARD” in the Name field.
Enter the value from the following table that corresponds to your hardware in the Value field.

...

Board Name

...

CURRENT_BOARD Value

...

Nucleo

...

0

...

Sparrow v1.0

...

1

...

Sparrow v1.1

...

2

Select the Add to all configurations checkbox
Select the Add to all languages checkbox
Click OK
Click Apply and Close

Build Sparrow Firmware

Select the sparrow project.
Click the hammer icon to Build 'Debug' for project 'sparrow'.

Install Sparrow Firmware

Before you can install binaries you must first specify a Run Configuration.

Select Run > Run Configurations... from the menu.
From the Run Configurations dialogue you will select STM32 Cortex-M C/C++ Application > Device Debug.
All the default values should be correct, and now you can press the Run button.

...

Once you have specified a Run Configuration, you can then use Run Device Debug from the tool bar.

Select the sparrow project.
Click the play icon (green circle with white triangle) to Run Device Debug.

Debug Sparrow Firmware

Select the sparrow project.
Click the bug icon to Debug Device Debug.

VSCode

[LINUX ONLY] Utilizing the Containerized Development Environment
NOTE: Be sure to attach your Sparrow device to your machine before you launch the development environment, so /dev/bus/usb can be captured by the container.
Once you have installed the “Remote - Containers” VSCode extension, then you can click the small green box in the lower-left corner of the VSCode window.

...

Then select “Reopen in Container” from the dropdown menu.

...

Troubleshooting

Unsaved Worksapce If you see “you must have your workspace in a folder containing all folders” this can mean the workspace is unsaved, so be sure to save the workspace first.

Windows VM Troubleshooting

Repo Error during container Build (on Virtual Host, e.g. Parallels running Windows on OSX)

FIX: This is a clock synchronization problem. Restart the virutal Windows Host.

=> [internal] load build definition from Dockerfile 0.1s => => transferring dockerfile: 32B 0.0s => [internal] load .dockerignore 0.1s => => transferring context: 2B 0.0s => [internal] load metadata for docker.io/library/debian:stable-slim 10.6s => CACHED [1/6] FROM docker.io/library/debian:stable-slim@sha256:608a500 0.0s => ERROR [2/6] RUN ["dash", "-c", " apt-get update --quiet && apt-ge 3.9s

[2/6] RUN ["dash", "-c", " apt-get update --quiet && apt-get install --as sume-yes --no-install-recommends --quiet bzip2 ca-certificates cm ake curl git make && apt-get clean && apt-get purge && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* "]: #4 2.751 Get:1 http://security.debian.org/debian-security stable-security InRele ase [44.1 kB] #4 3.110 Get:2 http://deb.debian.org/debian stable InRelease [116 kB] #4 3.580 Get:3 http://deb.debian.org/debian stable-updates InRelease [39.4 kB] #4 3.854 Reading package lists...E: Release file for http://security.debian.org/ debian-security/dists/stable-security/InRelease is not valid yet (invalid for an other 30d 15h 8min 20s). Updates for this repository will not be applied. #4 3.875 E: Release file for http://deb.debian.org/debian/dists/stable/InRelease is not valid yet (invalid for another 13d 9h 11min 47s). Updates for this repos itory will not be applied. #4 3.875 E: Release file for http://deb.debian.org/debian/dists/stable-updates/I nRelease is not valid yet (invalid for another 31d 12h 46min 3s). Updates for th is repository will not be applied. #4 3.884

executor failed running [dash -c apt-get update --quiet && apt-get install --assume-yes --no-install-recommends --quiet bzip2 ca-certificates cmake curl git make && apt-get clean && apt-get purge && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* ]: exit code: 100

Invalid Mount Config for type bind

The fix here is to be sure there is a Linux subsystem installed in addition to the ones installed by Docker Desktop. Running wsl —install -d ubuntu

Will fix this. (And be sure to enable docker integration for that WSL distro in docker desktop.)

[27174 ms] Start: Run: docker run --sig-proxy=false -a STDOUT -a STDERR --mount type=bind,source=z:\b\sparrow-sensor-framework,target=/workspaces/sparrow-sensor-framework,consistency=cached --mount type=volume,src=vscode,dst=/vscode -l vsch.local.folder=z:\b\sparrow-sensor-framework -l vsch.quality=stable -l vsch.remote.devPort=0 --entrypoint /bin/sh vsc-sparrow-sensor-framework-506417bf5f9c63e2c9ace81a4b8205bf -c echo Container started ; trap "exit 0" 15; while sleep 1 & wait $!; do :; done docker: Error response from daemon: invalid mount config for type "bind": bind s ource path does not exist: /run/desktop/mnt/host/uC/Mac/Home/b/sparrow-sensor-fr amework. See 'docker run --help'. [28619 ms] Start: Run: docker ps -q -a --filter label=vsch.local.folder=z:\b\sparrow-sensor-framework --filter label=vsch.quality=stable [29547 ms] Command failed: docker run --sig-proxy=false -a STDOUT -a STDERR --mount type=bind,source=z:\b\sparrow-sensor-framework,target=/workspaces/sparrow-sensor-framework,consistency=cached --mount type=volume,src=vscode,dst=/vscode -l vsch.local.folder=z:\b\sparrow-sensor-framework -l vsch.quality=stable -l vsch.remote.devPort=0 --entrypoint /bin/sh vsc-sparrow-sensor-framework-506417bf5f9c63e2c9ace81a4b8205bf -c echo Container started ; trap "exit 0" 15; while sleep 1 & wait $!; do :; done

If the drive containing the project is a network drive it may not be mounted by default in the linux distro enabled for docker. https://www.public-health.uiowa.edu/it/support/kb48568/

Oh, but even that is not enough - seems network drives (parallels mapping Mac drive to a local Windows drive) doesn’t show up when opening the project in the container. Whether opened from the Explorer, or from a mounted drive in WSL (e.g. /mnt/z )

What does work:

opening VSCode on a local Windows drive, and then re-opening as a container
opening wsl, and cd’ing to the same folder in the windows mount (e.g. /mnt/c/blues/sparrow-sensor-framework) and running code .
copying the project to a linux folder under ~/ and runinng code . from there. (e.g. to \\wsl$\ubuntu\home\mat\blues\sparrow-sensor-framework)

What does not work

...

The Sparrow family consists of one or more Sensors which communicate JSON-formatted Notes using a LoRa radio to a Gateway with which they have been manually paired. A Sparrow Gateway will forward messages received from its paired Sensors to the cloud via Notecard. Conversely, it will also forward messages received from the cloud via Notecard to an associated Sensor.

The goal of this guide is to provide everything you need to help you set up, configure and start collecting data from the Sparrow platform!

Prerequisites

Hardware

Sparrow Essentials Board
Sparrow Reference Sensor Board
Notecard (preferably Note-WiFi)
Notecarrier-AL (with Qwiic Connector)
STLINK-V3MINI
Qwiic Cable
USB Type A-to-Micro Cable
LiPo (2000mAh)
(2x) AAA Batteries

Software

Firmware

Sparrow Accelerator Sensor Firmware (clone using --recursive)

Tooling

Native Installation
- CMake (must be v3.14 or greater)
- Make
- ST-LINK GDB Server (via STMCubeIDE)
- STM32CubeProg
- VSCode “Cortex-Debug” Extension
- VSCode “Cortex-Debug: Device Support Pack - STM32WL” Extension
- Terminal Program (choose one)
  - [MacOS] CoolTerm
  - [Linux] GTKTerm
  - [Windows] PuTTY
  - Arduino Serial Montior (Arduino IDE)
- [OPTIONAL] GNU ARM toolchain (also packaged with STM32CubeIDE)

NOTE: Be sure to add/install all tools/libraries into your system path.
This may be necessary of all tools, but is especially important for ST-LINK_gdbserver and its shared library dependency, libSTLinkUSBDriver.so (or platform specific equivalent).
Linux:

Code Block

language	none

export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.linux64_2.0.0.202105311346/tools/bin:${PATH}
export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.linux64_2.0.100.202110141430/tools/bin:${PATH}
export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin:${PATH}
export LD_LIBRARY_PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/native/linux_x64:${LD_LIBRARY_PATH}

Mac OS (set in your ~/.bashrc file or whatever terminal you prefer):

Code Block

language	none

export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.macos64_2.0.0.202105311346/tools/bin:$PATH"export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.macos64_2.0.0.202105311346/tools/bin:$PATH"
export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.macos64_2.0.100.202110141430/tools/bin:$PATH"
export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_2.0.100.2109301221/tools/bin:$PATH”
export DYLD_LIBRARY_PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_2.0.100.202109301221/tools/bin/native/mac_x64:$DYLD_LIBRARY_PATH”

[LINUX ONLY] Containerized Development Environment
- Docker
- VSCode “Remote - Containers” Extension

Understanding the Hardware

At its core the Sparrow is a single piece of hardware, which comes in one of three configurations:

Sparrow Core Board
The most basic configuration, it comes completely depopulated. It is the theoretical starting point for someone to take the hardware, prototype with their own sensors, and then make their own PCB based on our design.
Sparrow Essentials Board
Designed for rapid prototyping, it comes populated with the following items:
- Cortex Debug Connector
- Female Pin Headers
- RESET/BOOT Buttons
- LiPo JST Connector
- Qwiic Connector
- Coin-cell Battery Holder
Sparrow Reference Sensor Board
Just add batteries and go. The reference sensor board comes with an integrated BME280 and PIR sensor. Once this device has been paired with a Gateway, then this device will start automatically capturing real data that you can work with while configuring your Notehub project.
It comes populated with the following items:
- Bosch BME280 (temp/humidity/pressure) Sensor
- PIR (motion) Sensor
- Cortex Debug Connector
- RESET/BOOT Buttons
- (2x) AAA Battery Holder

Unified Firmware, Split Personality

All the different Sparrow configurations run off the same firmware. Once the firmware boots, it looks for a Notecard (of any flavor) on the I2C bus. If it finds one, then it decides that it is an Essentials Board which is wired up as part of a Sparrow Gateway. If not, it then looks for a BME280 environmental sensor on the I2C bus. If it finds one, then it decides it is a Reference Sensor Board. However, if it finds neither, then it defaults to behaving as a Core Board.

Hardware Setup

Sparrow Gateway

Construction

On boot, the Sparrow firmware will begin looking for a Notecard on its I2C bus. If it discovers one, then it will assume the “Gateway” personality.

To construct a Sparrow Gateway, connect your Sparrow Essentials Board to your Notecarrier using the Qwiic cable and Qwiic connectors.

You must connect the LiPo battery to the JST connector on Notecarrier, and not the JST connector on the Sparrow.
Notecarrier DIP switch must be set to 3V3, instead of 1V8.
Oh no, my hardware doesn’t have a Qwiic Connector!?!
Pin Mapping Table

Notecarrier	Sparrow Gateway	Qwiic Color
<VIO	<VIO	RED
GND	GND	BLACK
SCL	SCL	YELLOW
SDA	SDA	BLUE

NOTE: If you have a Qwiic connector breakout, you can connect to the Qwiic connector of the Sparrow, and the same pins on the Notecarrier as above.

Connect to Notehub

If you are using a Wi-Fi Notecard, be sure to connect to your local network.

Code Block
{"req":"card.wifi","ssid":"<ssid name>","password":"<password>"}

There are two ways to connect your project to Notehub (choose one):

Configure the Notecard to connect to your Notehub product directly over USB (as you normally would).
Code Block
{"req":"hub.set","product":"<your_product_id>"}
Update the NOTECARD_PRODUCT_UID variable in sparrow-lora/Application/config_notecard.h to force your Sparrow Applications to connect to the desired Notehub product.

NOTE: If neither your Notecard nor the settings file are configured, then the Gateway will prompt you to configure the Notecard using a hub.set request.

WARNING: The dip switch on the Notecarrier-AL MUST be set to 3V3 when using a Wi-Fi Notecard.

Sparrow “Application Host” Node

Once the Sparrow firmware has decided it is NOT the “Gateway” personality, then it will assume the “Application Host” personality. A one-time pairing must be performed between every Application Host and Gateway. After being successfully pairing the Sparrow Sensor Reference Board, the BME280 and PIR sensors will be automatically detected by the firmware, and the device will begin to capture and report data to Notehub without any further configuration.

Manual Configuration of a Sparrow Node Details
Use the MAC of the Sparrow node as the Note ID, and update the following fields:
- name - A friendly name for the device
- loc - The location of the Sparrow Node
  NOTE: By convention, the loc field should be the GPS coordinates of the Node in OLC format (more info)

Example:
{"req":"note.update","file":"config.db","note":"20323746323650050042000b","body":{"name":"Office","loc":"8624G9CM+XM"}}

Radio Frequency

The Sparrow uses the LoRa protocol, and operates on the ISM (industrial, scientific, medical) band. Unfortunately, the ISM band is not standardized globally, so the frequency of the Sparrow must be set to operate the region in which it is being used. There are a set of DIP switches on the Sparrow, which allow you to easily select the transmission band.

WARNING: For legal use in the US and Canada, the Sparrow DIP switches MUST be set to the OFF position on all boards.

Pairing

Pairing requires a Sparrow Gateway and a Sparrow Node. This means each Sparrow device must have assumed the correct personality. This is a requirement, because the Gateway is responsible for storing the encryption keys and topology related to the hub and spoke network.

Pairing is straight-forward and easy to do, just follow the pairing instructions below.

Sparrow Usage/Operation

Understanding Hardware Behaviors

Button Behaviors

PAIR
- Held at Boot - Enable tracing logs over debug UART.
- Press
  - gateway - Enter pairing mode.
  - leaf-node
    - unpaired - Enter pairing mode.
    - paired - Send test message to gateway.
- Press & Hold - Enable "soft access point" on attached Note Wi-Fi.
  Press & Hold (30 seconds) - Reset to factory settings.
RESET - Press to reset device
BOOT - Press to enter bootloader mode (DFU)

LED Behaviors

Blue (PAIR) - Pairing mode.
- The Gateway will accept incoming requests
- A Node will be pinging, searching for a Gateway.
Green (RX) - Receive mode, waiting for an application to send it data.
Red (TX) - Transmit mode, actively sending data.
Blue & Green - Scanning for gateway (red will blink with each ping).
Red & Green - Attempting to send, but waiting for clear air (i.e. listening before speaking).
Red & Green & Blue
- steady on - booting.
- crawling
  - on start up - Gateway is connecting to Notehub.
  - on PAIR button hold - SoftAP is active.
- flash - Last operation acknowledgment.
  3 flashes - Factory reset has completed.

Pairing a Sensor to the Gateway

Press PAIR on the Sparrow Node
Press PAIR on the Sparrow Gateway

Pairing the devices is easiest when they are separated from each other (opposite sides of the table should be fine). Once the PAIR button has been pressed, the LED lights will begin to crawl until the devices have been paired. Once the devices have paired, the lights will flash to acknowledge success.

Building/Flashing/Debugging the Firmware

STM32CubeIDE

Load the project into your workspace

...

Open the STM32CubeIDE application.
Navigate to File > Open Projects from File System....
Press the Directory... button.
Open the hidden folder, .STM32CubeIDE, from the newly cloned repository.
Press the Finish button.

Update Build Defines

NOTE: If you have the v1.1 hardware then you may skip this section...

Right-click on the project, sparrow (in .STM32CubeIDE) and select Properties.
Unfold the C/C++ General menu.
Select Paths and Symbols.
Select the # Symbols tab.
Select “GNU C” from the Languages column
Click Add....
Enter “CURRENT_BOARD” in the Name field.
Enter the value from the following table that corresponds to your hardware in the Value field.

Board Name	`CURRENT_BOARD` Value
Nucleo	0
Sparrow v1.0	1
Sparrow v1.1	2

Select the Add to all configurations checkbox
Select the Add to all languages checkbox
Click OK
Click Apply and Close

Build Sparrow Firmware

Select the sparrow project.
Click the hammer icon to Build 'Debug' for project 'sparrow'.

Install Sparrow Firmware

Before you can install binaries you must first specify a Run Configuration.

Select Run > Run Configurations... from the menu.
From the Run Configurations dialogue you will select STM32 Cortex-M C/C++ Application > Device Debug.
All the default values should be correct, and now you can press the Run button.

...

Once you have specified a Run Configuration, you can then use Run Device Debug from the tool bar.

Select the sparrow project.
Click the play icon (green circle with white triangle) to Run Device Debug.

Debug Sparrow Firmware

Select the sparrow project.
Click the bug icon to Debug Device Debug.

VSCode

[LINUX ONLY] Utilizing the Containerized Development Environment
Once you have installed the “Remote - Containers” VSCode extension, then you can click the small green box in the lower-left corner of the VSCode window.

NOTE: Be sure to attach your Sparrow device to your machine before you launch the development environment, so /dev/bus/usb can be captured by the container.

...

Then select “Reopen in Container” from the drop-down menu.

...

Update Build Defines

NOTE: If you have the v1.1 hardware then you may skip this section...

Identify the value associated with your “current board” from the following table:

...

Current Board	Value
Nucleo	0
Sparrow v1.0	1
Sparrow v1.1	2

Identify the value associated with your “current board” from the proceeding table.
Update the CMakeLists.txt file in the root folder of the workspace.
Add an entry for “CURRENT_BOARD” (e.g. CURRENT_BOARD=1) in the following block...
Code Block
# Set global compile settings add_compile_definitions( STM32WL55xx CORE_CM4 )
[OPTIONAL][Intellisense Only] Update the .vscode/c-cpp-properties.json file.
Add an entry for “CURRENT_BOARD” (e.g. "CURRENT_BOARD=1",) in the following block...
Code Block
"defines": [ "CMAKE_TOOLCHAIN_FILE=${workspaceFolder}/arm-gcc-toolchain.cmake", "CORE_CM4", "STM32WL55xx" ],

...

Manual CMake and Make build instructions, look here.
The Sparrow project works just as any standard CMake project, to build it you will:
1. Create a build folder
2. Enter the build folder
3. Call cmake from inside the build folder
  Call make from inside the build folder
Example (from the root folder):mkdir build && cd build/ && cmake .. && make -j

Install Sparrow Firmware

Navigate to, Terminal > Run Task...
Select, Sparrow: Flash Firmware Using STM32_Programmer_CLI

Manual STM32_Programmer_CLI flash instructions, click here.
STM32_Programmer_CLI --connect port=SWD reset=HWrst --write sparrow.elf --verify --go

Debug Sparrow Firmware

Hotkey: Ctrl+Shift+D

Select Run and Debug menu from the leftmost toolbar.
Press the green “Play” button next to Cortex Debug.

...

My debugger is not working!
The first run of the v1.1 Sparrow Reference Sensor Boards had the 2x7-pin debug connectors installed backwards. As they are installed, the keyed Cortex debug connector can not be plugged-in correctly. The connectors were reworked, so be sure to plugin the debugger with keyed tab slotted into the “rough” side.

):mkdir build && cd build/ && cmake .. && make -j

Install Sparrow Firmware

Navigate to, Terminal > Run Task...
Select, Sparrow: Flash Firmware Using STM32_Programmer_CLI

Manual STM32_Programmer_CLI flash instructions, click here.
STM32_Programmer_CLI --connect port=SWD reset=HWrst --write sparrow.elf --verify --go

Debug Sparrow Firmware

Hotkey: Ctrl+Shift+D

Select Run and Debug menu from the leftmost toolbar.
Press the green “Play” button next to Cortex Debug.

...

Collecting Logs

Use an STLINK-V3MINI to connect to your device, you can use a terminal emulator to view the debugging output on the serial port that appears on your computer.

...

Connect your computer to STLINK-V3MINI using a USB A-to-Micro, then connect the STLINK-V3MINI to your device using the Cortex debug connector.

v1.0 HARDWARE ONLY

FTDI

Pin Mapping

Sparrow FTDI Cable Color GND GND BLACK LPRX TXD ORANGE LPTX RXD YELLOW

...

.

Versions Compared

Old Version 10

New Version Current

Key

Prerequisites

Hardware

Software

Understanding the Hardware

Hardware Setup

Sparrow Gateway

Sparrow “Application Host” Node

Radio Frequency

Pairing

Sparrow Usage/Operation

Understanding Hardware Behaviors

Pairing a Sensor to the Gateway

Building/Flashing/Debugging the Firmware

STM32CubeIDE

VSCode

Prerequisites

Hardware

Software

Understanding the Hardware

Hardware Setup

Sparrow Gateway

Sparrow “Application Host” Node

Radio Frequency

Pairing

Sparrow Usage/Operation

Understanding Hardware Behaviors

Pairing a Sensor to the Gateway

Building/Flashing/Debugging the Firmware

STM32CubeIDE

VSCode

Collecting Logs