Boards

BoardDescription
Air Quality WingAir Quality WingFeatherwing for Air Quality Monitoring
nRF9160 FeathernRF9160 FeatherFeather using nRF9160 to connect via LTE CAT M1 or CAT NB1.
Sparkfun Thing Plus nRF9160Sparkfun Thing Plus nRF9160Thing Plus using nRF9160 to connect via LTE CAT M1 or CAT NB1.

Air Quality Wing

Air Quality Wing

Prototype of the Air Quality Wing v6 pictured.

The Problem

As wildfires ravage parts of the USA and smog has loomed in our skies it’s become more important than ever to make sure you’re breathing clean air. Some folks may just go buy an air purifier. But, how do you know it works? How do you know if it’s powerful enough to protect your whole space?

Like a scientist, you can test it with an Air Quality Wing.

What is it?

The Air Quality Wing is an all-in-one air quality sensor and development board. It brings together a trio of sensors to give you as many data points as possible. That way, there won’t be anything missing when you go to measure the air inside your home or workplace.

Here's what's included:

Particulate Sensing

The most important sensor is the Honeywell HPMA115S0 dust sensor (available as a purchase option). This sensor counts the concentration of potentially harmful particulates in the air. It can detect both large particles 10µm in diameter and smaller ones less than 2.5µm in diameter. These readings are known as PM10 and PM2.5 respectively.

Sensing Volatile Compounds

Second to that, is the Sensirion SGP40. This senses volatile organic compounds (VOCs). These types of readings are useful in places where there may be combustion. (Think stoves, furnaces, etc) It can act as an early warning mechanism. That way you stay safe, happy and healthy!

Temperature and Humidity

Finally, the Sensirion SHTC3 temperature and humidity sensor. These readings can be used on their own. Additionally they’re used by the SGP40 to compute an accurate TVOC.

Flexible Power Sources

No outlet nearby where you want to measure? No problem!

You can easily plug in almost any lithium polymer battery to your Feather based development board board and use it immediately. The Air Quality Wing also has extra circuitry that allow you to switch between USB and battery without user input.

The Air Quality Wing also features an optional battery backpack which holds a 850mAh CR2 battery.

Air Quality Wing Backpack

Simply solder it on and you're good to go!

Software support

Drivers for Zephyr are nearly complete. Drivers for Embedded Rust are planned. All software and hardware is open source!

Purchase

The Air Quality Wing is available for pre-order here: https://www.jaredwolff.com/store/air-quality-wing/ Board will be shipping late September/Early October 2021.

Previous versions

For more info on earlier versions of the Air Quality Wing go here.

Specifications

The Air Quality Wing v6 contains the following sensors and features:

  • SHTC3 temperature and humidity sensor

    • Humidity range 0 - 100% (Accuracy ±2% RH)
    • Temperature range -25 - 100°C (Accuracy ±0.2°C)
    • Less than 1 μJ per measurement
    • 1.62 - 3.6V operation
    • 2 x 2 x 0.75 mm3 DFN package
    • Communicates via I2C
  • SGP40 TVOC sensor

    • Voltage range of 1.7–3.6 V
    • Generates raw values that can be computed to relative air quality measurement in firmware
    • Sensor size 2.44 x 2.44 x 0.85mm
    • Always on average power consumption down to 2.6 mA/6 mW
    • Communicates via I2C
  • HPMA115S0 PM2.5 sensor

    • Device power controlled by D5/PM2.5 EN pin
    • Onboard 5V boost power supply and bypass
    • Operates on both 5V and VBAT
    • Digital IO uses 3.3V
    • Provides both PM10 and PM2.5 values
    • Measurement range 0-1000 μg/m3
    • Communicates via UART
  • Additional power control to I2C devices via D4/I2C EN pin

  • CR2 battery holder on bottom side (optional)

Electrical

Required input

  • 3.3V Input: 3.3V ± 0.3V

  • Battery Max Input: 5.2V

  • Battery Min Input: 3.0V

  • 5V Max Input: 5.2V

  • 5V Min Input: 4.8V

Important safety note!!

If USB is applied while the battery is inserted, this will cause most feather boards to activate their charger. This may damage the battery and/or the attached boards. Remove the battery at all times when USB is inserted.

Enable Pins

  • Max Input: 3.3V ± 0.3V

Recommended Communication Speeds

  • I2C: 100KHz
  • UART: 9600 BAUD

License

Circuit Dojo LLC accepts no liablity if this board is used outside the recommended parameters. See the CERN Open Hardware Licence Version 2 - Weakly Reciprocal license for more details: https://github.com/circuitdojo/air-quality-wing-hardware/blob/master/LICENSE

Getting Started

There are a few ways you can get started with the Air Quality Wing. Here are some of the configurations you can put your board in depening on the application:

  1. Headers soldered down for use with a Feather doubler or tripler

    This configuration is perfect if you need to interface with other Feather/Featherwings which already have headers soldered. Here is an example configuration below:

    Headers down configuration in doubler

  2. Header-up with (optional) battery backpack

    If you're tight on space, you can stack the Air Quality Wing with other Feather compatible boards vertically. Additionally you can solder the battery backpack to the "back" side so everything is together in one package.

    TODO: show picture of this configuration

  3. Soldering wire connections directly to the board:

    If you are feeling adventureous, you can also solder direct wire connections to the I2C, power/ground and UART connections. Recommended for more custom or permanent projects.

    TODO: show picture of this configuration

Zephyr Examples

The Air Quality Wing has first class support on Zephyr. It can be used with almost any board that is supported by Zephyr.

Here's the code.

Prebuilt binaries are also located here. (Under Github actions) Not all binaries will work out of the box. Golioth binaries require you to edit golioth.conf before using. (See below.)

Sample descriptions

The code is a a work in progress but includes a BLE example, nRF9160 Feather example an standalone sample.

Basic

The Basic example connects to and obtain samples on a regular basis. They're printed out to the console.

BLE (Bluetooth Low Energy)

The BLE example does the same as the Basic but also connectable via Bluetooth. Once connected characteristics can be subscribed to and updated by the device.

Golioth

The Golioth example is the same as Basic but it also publishes to the Golioth IoT backend for integration with tools like Grafana.

Setting up your environment

Here is the minimal amount of steps to get an example working. This example is currently only configured for the nRF52 DK.

Hardware

If you do not have a PM2.5 sensor you can comment out &hpma_sensor, within sensors[] in main.c before building.

SDK Setup

If you didn't already, install Visual Studio code. You can download it here.

Marketplace

Once Visual Studio code is installed, download the extension here. 👈

Once loaded it will also install all necessary VSCode dependencies.

Then install Git and Python.

Mac

Requires git and python3 to be installed. The easiest way to do that is with Homebrew.

> brew install git python3

Windows

Requires git and python to be installed.

Linux

Requires git,python and pip to be installed.

Use your distro's package manager of choice to install.

For example on Ubuntu:

sudo apt install git python3 python3-pip

Run Setup

Then open the command window (COMMAND+SHIFT+P on Mac or CTRL+SHIFT+P on other systems) and type Zephyr Tools: Setup

Setup

Init the repo

Then initialize this repo using the Zephyr Tools: Init Repo command:

Init repo

Make sure you use https://github.com/circuitdojo/air-quality-wing-zephyr-demo.git as the URL. It's best to select an empty folder to initialize the project to.

Then build the sample!

Build

You'll be prompted for a project and board. Make sure the board matches the supported boards. Current supported board targets include:

  • particle_xenon
  • circuitdojo_feather_nrf9160_ns
  • nrf52840dk_nrf52840

Here's what it will look like:

Choosing board Choosing app

Once the build completes you should get a Build complete! popup along with some success messages in the the terminal.

Build success

Golioth Configuration

You will need to edit golioth.conf with your credentials in order to connect to Golioth's backend. More instructions on setting up your credentials can be found here. You can also create devices and add credentials within the Golioth Console.

Loading using VSCode

Once built, place the device into bootloader mode:

  1. Hold the MODE button
  2. Then tap the RST button while holding mode
  3. Hold the MODE button until the Blue LED illuminates

Then, load using the Zephyr Tools: Load via Bootloader task.

Option for loading

Pay attention to the progress in the bottom console.

Option for loading

Once complete, the extension will reset your device and should start executing!

Important: make sure you close all console sessions with your nRF9160 Feather before programming using newtmgr. Otherwise the newtmgr image upload will timeout.

Building Manually

These commands are simlar to what the Zephyr Tools extensions uses. The programming commands are also included here.

nRF52840 DK

cd demo
west build -b nrf52840dk_nrf52840

Then flash using

nrfjprog --program build/merged.hex --chiperase --reset

or load via the bootloader

newtmgr -c serial image upload build/zephyr/app_update.bin && newtmgr -c serial reset

Xenon

cd basic
west build -b particle_xenon

Then flash using

nrfjprog --program build/merged.hex --chiperase --reset

nRF9160 Feather

cd basic
west build -b circuitdojo_feather_nrf9160_ns

Then flash using

nrfjprog --program build/merged.hex --chiperase --reset

You can also load using newtmgr. More information is here.

Zephyr Examples

The Air Quality Wing has first class support on Zephyr. It can be used with almost any board that is supported by Zephyr.

Here's the code.

Sample descriptions

The code is a a work in progress but includes a BLE example, nRF9160 Feather example an standalone sample.

Basic

The Basic example connects to and obtain samples on a regular basis. They're printed out to the console.

BLE (Bluetooth Low Energy)

The BLE example does the same as the Basic but also connectable via Bluetooth. Once connected characteristics can be subscribed to and updated by the device.

Golioth

The Golioth example is the same as Basic but it also publishes to the Golioth IoT backend for integration with tools like Grafana.

Setting up your environment

Here is the minimal amount of steps to get an example working. This example is currently only configured for the nRF52 DK.

Hardware

If you do not have a PM2.5 sensor you can comment out &hpma_sensor, within sensors[] in main.c before building.

Virtual Environment

One of the main dependencies for Zephyr is Python. Instead of installing the required packages directly to your system, I highly recommend use a virtual environment instead.

First lets make a project folder. We can call it aqw:

mkdir -p aqw

If you don't have virtualenv installed already, make sure you install it:

pip3 install virtualenv

Set up a python virtual environment:

virtualenv -p python3 env

Then enable it by running:

source env/bin/activate

Install west

west is the command line utility for Zephyr. You'll need it to build the firmware.

pip3 install west

Init and update project

Next we'll download the source code and install the dependencies.

west init -m https://github.com/circuitdojo/air-quality-wing-zephyr-demo.git  --manifest-rev main

Or already cloned locally:

west init -l .

Then run

west update

This will download all the dependencies. If there are ever fixes to this sample you'll need to pull the changes and then re-run west update:

git pull && west update

Install remaining python dependencies

Finally, there are some important dependencies needed to build your freshly cloned Zephyr repository. Let's install those here.

pip3 install -r zephyr/scripts/requirements.txt

Install toolchain

  • For Mac run the following: (it does require you install wget. brew is an easy way to do so: brew install wget)

    cd ~
    wget "https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-mac.tar.bz2"
    tar xvfj gcc-arm-none-eabi-9-2019-q4-major-mac.tar.bz2
    rm gcc-arm-none-eabi-9-2019-q4-major-mac.tar.bz2
    

    Note for Catalina users you will get an error when running these utilities for the first time. You must allow them to be executed in your Security preferences.

    Error running ARM Toolchain

  • For Windows you can download and install the toolchain with this direct link.

Golioth

You will need to edit golioth.conf with your credentials in order to connect to Golioth's backend. More instructions on setting up your credentials can be found here. You can also create devices and add credentials within the Golioth Console.

Building

nRF52840 DK

cd demo
west build -b nrf52840dk_nrf52840

Then flash using

nrfjprog --program build/merged.hex --chiperase --reset

or load via the bootloader

newtmgr -c serial image upload build/zephyr/app_update.bin && newtmgr -c serial reset

Xenon

cd basic
west build -b particle_xenon

Then flash using

nrfjprog --program build/merged.hex --chiperase --reset

nRF9160 Feather

cd basic
west build -b circuitdojo_feather_nrf9160_ns

Then flash using

nrfjprog --program build/merged.hex --chiperase --reset

Rust Examples (WIP)

Rust source can be found here:. It's currently a work in progress.

Arduino/Particle

Particle console

The Arduino library has been updated to work with V6! See the quickstart below.

Sample code is located here: https://github.com/circuitdojo/air-quality-wing-code

Library is located here: https://github.com/circuitdojo/air-quality-wing-library

Quick Start:

This quick start assumes you have Particle Workbench installed.

  1. Clone this repo onto a place on your machine: git clone git@github.com:circuitdojo/air-quality-wing-code.git
  2. Init the library submodule using git submodule update --init --recursive
  3. Open the repo with Visual Code: (code . using the command line, or file->open)
  4. Open /src/AirQualityWing.ino
  5. Select your target device in the lower bar (Options are: argon and boron)
  6. Hit cmd + shift + p to get the command menu
  7. Select Compile application (local). You can also choose Cloud flash as long as board.h has not been modified.
  8. Enjoy playing around with your Air Quality Wing!

This example has been tested with DeviceOS 3.1.0. It's recommended to upgrade if you have problems.

Enclosure

The new enclosure will be open source and available soon. Currently still a work in progress.

Original Enclosure

Full

Download link:

Click here to download all the .STL files and get printing!

The features:

  • Detachable lithium battery compartment.
    • Maximum battery size:
    • Width: ~114 mm
    • Length: ~48 mm
    • Height: ~31 mm (includes battery expansion wiggle room)
    • Secures with M2.5 screws
  • Precision openings for the Honeywell HPMA115S0
  • Dual purpose top opening for Particle RGB LED and Ventilation
  • No fastener clip top
  • Enough room for the original AQW and Reduced Size Version (v5 and newer)
  • Knock outs for antenna connection and battery connection
  • USB port cutout to run off USB power

Here are a few photos:

Top Battery Boards Inside USB

Changelist

5/23/2020: v54

  • Reduced the height slightly so the HPMA doesn't move as much

5/13/2020: v53

  • Re-designed top snap
  • Increased length to give more room for cables.
  • Tweaked height for HPMA sensor (so it doesn't rattle around)
  • Antenna break outs are real!
  • USB fit improvements

Files/Source

Source

This design is OSHWA certified! Check out the certification page here.

This boards source is located on Github.

Pre-compiled samples

The AQW library for Zephyr is configured for CI/CD deployments. You can get the latest .hex and app_update.bin files from Github here. (Under Github actions)

Purchase

The Air Quality Wing v6 has arrived! It's available here:

Circuit Dojo Logo

Support

The best place for support is the Circuit Dojo support forum. In most cases you'll recieve a response within 1-2 business days. For more information see our Terms of Service.

If you have a question relating to your order please contact support@jaredwolff.com

The nRF9160 Feather is licenced under the CERN Open Hardware Licence Version 2 - Weakly Reciprocal For more details on warranty and liability click here.

Changelog

v6 - (October 2021)

Changed:

  • Formfactor to standard Feather size
  • Replaced temperature/humidity sensor with SHTC3
  • Replaced TVOC sensor with SGP40
  • Changed MCP1640 package to DSON from SOT23-5
  • Hatched ground planes on both top and bottom
  • Re-designed sensor placement
  • Thermal isolation slots for SHTC3
  • Pinout for PM2.5 connector reverted back to original design (allows for bidirectional use of cable)

Added:

  • Added I2C power control to D4
  • Added battery backpack (CR2 holder)

v4

  • Relocated the Si7021 to a separate "lily pad" for heat isolation

v3

  • Fixed bug related supply voltage not being stable to the HPMTA115S0
  • Relocated D7 to D5 for CCS811 reset signal
  • Changed connector pinout. That way the cable does't have to be twisted.

v2

  • Added ferrite to shunt noise
  • Swapped out MCP1624 with MCP1640

Introduction to the nRF9160 Feather

The nRF9160 Feather by Jared Wolff (aka Circuit Dojo LLC) is an electronics development board. It features a Nordic Semiconductor nRF9160-SICA part. This part is capable of both CAT M1 LTE and NB-IoT for communication with the outside world. It's compatible primarily with Zephyr via the nRF Connect SDK. Other toolchains and languages coming soon to a Github repository near you.

nRf9160 Feather Trimmed

Overview

Diagram

This board can be powered several ways. The most popular way to power Feather boards is by using the USB port. This board is no exception. It works well across both USB and LiPoly batteries.

The board is designed from the ground up to be power efficient at the most used power state: standby. That's right, if you're developing something that's battery powered, your most used state will usually be standby mode. As of this writing the estimated current draw in this state should be < 10µA. That's approximately 1.71 years on a 150mAH cell!

Speaking of power, this board also has a fully fledged DC/DC Buck with an atonishing <1uA quiescent current!

This board also sports some external flash for storing your application data. Use it with the built in support for LittleFS in Zephyr. Or, use one of your choice! What ever tickles your fancy.

Finally, but not least, the nRF9160. I've been watching this part very carefully since the CEO had it locked in a mysterious black case years back. It's here and it's real and the module is half the price of other modules. I won't bore you with all the technical details. (Technical details get you excited? Go here.) Needless to say, it's awesome.

Logos

I'll be launching in collaboration with the awesome folks at Hackster.io and GroupGets. We're all very excited to bring these boards to you!

If you want real-time updates, sign up here and i'll stay in touch. I can't wait to share more with you!

Specifications and Requirements

Specs photo

Technical Details

  • Nordic nRF9160*
    • Microcontroller
      • ARM Cortex M33
      • 1MB Flash
      • 256kB RAM
      • ARM® TrustZone®
      • ARM® Cryptocell 310
      • Up to 4x SPI, I2C and UART with Easy DMA
      • I2S w/ EasyDMA
      • 4x PWM with EasyDMA
      • 12bit SADC with EasyDMA
      • 2x RTC
      • PPI (Programmable peripheral interconnect) interface
    • Radio
      • Transceiver and baseband
      • 3GPP LTE release 13 Category M1 and NB1 compliant
      • 3GPP release 14 NB2 compliant
      • GPS receiver (GPS L1 C/A supported) - Active antenna only.
      • RF Transceiver for global coverage supporting bands:
        • Cat-M1: B1, B2, B3, B4, B5, B8, B12, B13, B14, B17, B18, B19, B20, B25, B26, B28, B66
        • Cat-NB1/NB2: B1, B2, B3, B4, B5, B8, B12, B13, B17, B18, B20, B25, B26, B28, B66
      • Supports 4FF Nano SIM
  • Micro USB connection for USB-to-Serial and DFU
  • Pre-programmed MCUBoot bootloader
  • External NOR Flash by Winbond
    • 4MB of space (Upgraded for all boards as of August 2, 2020!)
    • Max bus speed of 133MHz
    • Standard SPI
  • Power supply
    • 3.3V Buck with < 1uA of quiesent current. 750 mA ouput max
    • Operating range 3.0 to 6.5V
    • External LiPoly battery connection (JST SPH type)
    • LiPoly set to 300mA with indication
  • Programmer
    • Capable of interfacing with Jlink and CMSIS-DAP based programmers
    • Use with a Tag Connect TC2030-CTX-NL over Serial Wire Debug (SWD)
  • Low Power RTC on board for time keeping and as a low power wakeup source.
  • User I/O
    • Standard feather form factor GPIOs (0.1" pitch)
    • 2x buttons (1 Reset, 1 General Purpose)
    • 1x Blue LED connected to D7
  • Antenna connections:
    • 1x U.FL for LTE with matching network
    • 1x U.FL for active GPS antennas
  • Feather form factor
    • 50.8mm x 22.86mm (2" x 0.9")

* nRF9160 tech specs provided from the nRF9160 Product Specification

Block Diagram

Electrical

Here are the elctrical specifications for the nRF9160 Feather. Most of the specifications here are based on the nRF9160 Product Specification. You can get the latest version of the nRF9160 Product Specification here. All previous versions can be found here.

Board Supply

  • Output voltage: 3.3V ± 0.3V
  • Max output current: 750
  • Active sleep current < 10µA

Pin Ratings (MD/A0-A5/D0-D8/TX/RX/CIPO/COPI/SCK/RST)

  • Max input voltage: 3.6V

Enable Pin

  • Max input voltage: 6.5V¹

¹Enable pin is active high.

External Power Supply

The nRF9160 Feather can be powered via battery or USB. See below for the specifics for each power source

USB Requirements

  • Operating range: 5V ± 0.2V
  • Current requirements: >500mA

Battery Requirements

  • Battery type: LiPoly
  • Operating range: 2.8-5.5V
  • Current/power rating: Able to support at least 2W of power
  • Battery capacity: > 300mAH²
  • Charging current: 294mA ± 10%

²Batteries below this capacity are not recommended nor supported.

Note: with charging circuit disabled (short JMP2) any input source up to 6.5V is supported.

GPS Antenna

GPS Antenna

The U.FL port on the nRf9160 Feather is to be used with an active GPS antenna only.

  • Antenna supply voltage: 3.3V ± 0.3V
  • Antenna current rating: 15mA

The port works with most U.FL based active antenna parts. The nRF9160 Feather has been tested and verified with the following parts:

Part NumberManufacturererDatasheetNotes
ACTPAT182-01-IPInventek SystemsLinkOffered as an addon

Cellular Antenna

The nRF9160 Feather has been tested with these approved antennas. They're chosen specifically to match the FCC requirements as indicated here.

Part NumberManufacturererDatasheetNotes
H2B4MH1F2F0100Unictron TechnologiesLinkIncluded
ANT-LTE-RPC-UFLLinxLinkGPS/GNSS, Rigid

Only tested antennas are supported. If you choose to use a different one, proceed at your own risk!

Getting Started

Start here

🚨Read this first🚨

There are some important things about the nRF9160 Feather before you get started:

  1. The nRF9160 Feater shouldn't be used with a battery less than 300mAH. More information in the specs section.
  2. If you need to debug your nRF9160 Feather, it requires an external programmer. More information on that in the Requirements for external programming section.
  3. If you're new to Zephyr, be sure to check out the Zephyr 101 series on Youtube!
  4. Looking for help? Check out the support forum: https://community.jaredwolff.com

What's included

nRF9160 Feather

  • 1x nRF9160 Feather board
  • 1x set of male headers (16 pin and 12 pin)
  • 1x wide-band LTE antenna
  • 1x getting started card
  • 1x IoT SIM

SDK and Development Environment Setup

Instructions below are based on using Microsoft's Visual Studio Code as your workspace. While you may choose a different editor, most of the steps remain the same.

Getting Started Sections

SDK Setup (Mac OS)

This page is all about getting your Mac compiling code for the nRF9160 Feather. Run into trouble during the process? Post your questions on the community forum.

Installing Extension

If you didn't already, install Visual Studio code. You can download it here.

Marketplace

Fortunately, it's a bit easier to get started with the VSCode extension. The VSCode is required along with a Python 3 and Git on your system before continuing.

Once Visual Studio code is installed, download the extension here. 👈

The easiest way to install git and python3 is with Homebrew.

> brew install git python3

Run Setup

Then open the command window (COMMAND+SHIFT+P on Mac or CTRL+SHIFT+P on other systems) and type Zephyr Tools: Setup

Setup

Init the repo

Then initialize this repo using the Zephyr Tools: Init Repo command:

Init repo

Make sure you use https://github.com/circuitdojo/nrf9160-feather-examples-and-drivers.git as the URL. It's best to select an empty folder to initialize the project to.

Then build the sample!

Build

You'll be prompted for a project and board. Make sure the board matches the supported boards. Current supported board targets include:

Here's what it will look like:

Choosing board Choosing app

Once the build completes you should get a Build complete! popup along with some success messages in the the terminal.

newtmgr (Used to load your application via USB serial bootloader)

newtmgr is the command line utility for loading code to your device. It is automatically installed with the VSCode extension. Lets configure it the rest of the way.

  1. If you'r on a newer version of OSX you'll need to install the drivers.

  2. Configuring is simple as running the Zephyr Tools: Setup Newtmgr command

    Setup newtmgr

    Select your serial port:

    Select serial port

    Then select the BAUD. (Use the default of 1000000) Once complete you're ready to run the Zephyr Tools: Load via Bootloader command.

    Select baud

Testing it

Now you can get to playing around with some of the nRF9160 Feather example code! Remember you'll always have to open a terminal using the Toolchain Manager to build code!

You can quickly test if your SDK is set up correctly by checking out the samples.

SDK Setup (Windows)

This page is all about getting your Windows machine compiling code for the nRF9160 Feather. Run into trouble during the process? Post your questions on the community forum.

Installing Extension

If you didn't already, install Visual Studio code. You can download it here

Marketplace

Once Visual Studio code is installed, download the extension here. 👈

Once loaded it will also install all necessary VSCode dependencies.

Then, install git and python if you don't have them already:

Run Setup

Then open the command window (COMMAND+SHIFT+P on Mac or CTRL+SHIFT+P on other systems) and type Zephyr Tools: Setup

Setup

Note: you may get an error that states "certificate has expired”. This is due to the certificates in VSCode being out of date. The easiest way to fix this is by updating your settings by setting http.systemCertificates to false.

http.systemCertificates: false

If you search for "system certificates" in your VSCode settings it should come right up.

Init the repo

Then initialize this repo using the Zephyr Tools: Init Repo command:

Init repo

Make sure you use https://github.com/circuitdojo/nrf9160-feather-examples-and-drivers.git as the URL. It's best to select an empty folder to initialize the project to.

If prompted for a branch, press 'Enter' to use the default.

Default branch

Then build the sample!

Build

You'll be prompted for a project and board. Make sure the board matches the supported boards. Current supported board targets include:

Here's what it will look like:

Choosing board Choosing app

Once the build completes you should get a Build complete! popup along with some success messages in the the terminal.

newtmgr (Used to load your application via USB serial bootloader)

newtmgr is the command line utility for loading code to your device. It is automatically installed with the VSCode extension. Lets configure it the rest of the way.

  1. Configuring is simple as running the Zephyr Tools: Setup Newtmgr command

    Setup newtmgr

    Select your serial port:

    Select serial port

    Then select the BAUD. (Use the default of 1000000) Once complete you're ready to run the Zephyr Tools: Load via Bootloader command.

    Select baud

Debugging newtmgr

Having trouble? You may need to install the Silabs VCP driver.. Download and install the CP210x VCP Windows option.

For more info in using newtmgr checkout the programming section of this documentation.

Testing it

You can quickly test if your SDK is set up correctly by checking out the samples. Make sure that you've closed and re-opened all terminals and Visual Studio Code so the environment is correct. Otherwise you may have issues compiling or flashing code.

SDK Setup (Linux - Ubuntu)

This page is all about getting your Linux machine compiling code for the nRF9160 Feather. Run into trouble during the process? Post your questions on the community forum.

Installing Extension

If you didn't already, install Visual Studio code. You can download directly from the Ubuntu Software Install utility. (or similar)

Ubuntu software install

Then we can continue installing the extension!

Marketplace

Fortunately, it's a bit easier to get started with the VSCode extension. The VSCode is required along with a Python 3 and Git on your system before continuing.

Once Visual Studio code is installed, download the extension here. 👈

Once loaded it will also install all necessary VSCode dependencies.

Then, install Git, Python, and Pip.

For example on Ubuntu:

sudo apt install git python3 python3-pip

Run Setup

Then open the command window (COMMAND+SHIFT+P on Mac or CTRL+SHIFT+P on other systems) and type Zephyr Tools: Setup

Setup

Init the repo

Then initialize this repo using the Zephyr Tools: Init Repo command:

Init repo

Make sure you use https://github.com/circuitdojo/nrf9160-feather-examples-and-drivers.git as the URL. It's best to select an empty folder to initialize the project to.

Then build the sample!

Build

You'll be prompted for a project and board. Make sure the board matches the supported boards. Current supported board targets include:

Here's what it will look like:

Choosing board Choosing app

Once the build completes you should get a Build complete! popup along with some success messages in the the terminal.

newtmgr (Used to load your application via USB serial bootloader)

newtmgr is the command line utility for loading code to your device. It is automatically installed with the VSCode extension. Lets configure it the rest of the way.

Configuring is simple as running the Zephyr Tools: Setup Newtmgr command

Setup newtmgr

Select your serial port:

Select serial port

Then select the BAUD. (Use the default of 1000000) Once complete you're ready to run the Zephyr Tools: Load via Bootloader command.

Select baud

Fixing serial port errors

Note if you get a Error: open /dev/ttyUSB0: permission denied error. You may need to add your user to the dialout group:

sudo usermod -a -G dialout <username>

This allows you to open a serial port without having to use sudo.

For more info in using newtmgr checkout the programming section of this documentation.

Testing it

You can quickly test if your SDK is set up correctly by checking out the samples.

Programming and Debugging

There are currently two ways of programming the nRF9160 Feather. You can use the built-in bootloader or use an external programmer.

Bootloader use

Currently the nRF9160 Feather uses the MCUBoot bootloader which comes standard with the nRF Connect SDK. It is the recommended way to load new firmware onto your nRF9160 Feather.

Using newtmgr

Note: v5 of the nRF9160 Feather no longer requires manual usage of the Mode + Reset pins. It's placed into bootloader mode automatically using the zephyr-tools CLI.

newtmgr comes with the VSCode extension. To learn more about configuring it see the setup page for your respective operating system:

Pre-check: MCUBoot needs to be enabled in your project before you can use it! Make sure that you have CONFIG_BOOTLOADER_MCUBOOT=y in your prj.conf

  1. Put your nRF9160 Feather into DFU mode.
    1. Hold the MODE button
    2. Then tap the RST button while holding mode
    3. Hold the MODE button until the Blue LED illuminates
  2. Building your application if you haven't already with west build. It will create a folder called build. The file we care about is build/zephyr/app_update.bin
  3. Load the file using the Zephyr Tools: Load via Bootloader task. Here's what it's doing behind the scenes:

Note:

  1. The transfer process is limited to 1M BAUD. In most cases it takes <15 seconds to transfer application code.
  2. The nRF9160 Feather does not respond to newtmgr commands unless it's in DFU mode. (See step 1 above to get it into DFU mode.)
  3. If you're having trouble completing a transfer you can also add these parameters to the end:
-r 3 -t .1 

Requirements for external programming and debugging

You can also use external programmers with the nRF9160 Feather. Here are the current supported external programmers:

  1. nRF5340-DK
  2. nRF9160-DK

Note: Most commercial J-Link programmers *should* work with the nRF9160 Feather. In particular the J-Link EDU Mini is a great choice if you're building non-commercial products. (Supports Cortex M33 processors. Untested at this time.)

🚨Important: the nRF52 and nRF51 based development kits do not work with the nRF9160 Feather!

👉Additionally, you'll also need a Tag-Connect cable. The nRF9160 Feather was designed to use the TC2030-CTX-NL. For more information check out Tag-Connect's product page.

Installing programmer software

In this next section, I'll be focusing on using the nRF5340-DK as the programmer of choice. These steps should not be different from other J-Link supported boards.

  1. Download your version of the nRF Command Line Tools

Windows

  1. Then, run the .exe that was downloaded. It will do all the heavy lifting for you.
  2. Run nrfjprog in a cmd window to make sure your install is working.
  3. You may also have to add JLink.exe to your path. It's the exact same proceedure as adding newtmgr except the path you're adding is C:\Program Files (x86)\SEGGER\JLink Paths updated for Windows for JLink
  4. Close/restart VSCode and your Command Prompt
  5. Run jlink.exe and make sure it opens.
    > jlink.exe
    SEGGER J-Link Commander V6.86f (Compiled Oct 23 2020 18:01:48)
    DLL version V6.86f, compiled Oct 23 2020 18:00:13
    
    Connecting to J-Link via USB...O.K.
    Firmware: J-Link OB-K22-NordicSemi compiled Jan 21 2020 17:33:01
    Hardware version: V1.00
    S/N: 960083363
    License(s): RDI, FlashBP, FlashDL, JFlash, GDB
    VTref=3.300V
    
    
    Type "connect" to establish a target connection, '?' for help
    J-Link>
    

Mac

  1. First run nRF-Command-Line-Tools_10_9_0_OSX.pkg
  2. Once that install is done, run JLink_MacOSX_V680a.pkg
  3. Open a fresh terminal window and run nrfjprog and jlinkexe to make sure your install is complete.

Setting up the nRF5340-DK

Here are a couple of close up shots of how to connect the nRF5340-DK:

nrf53-dk-connected

nRF9160 Feather w/ USB

nRF9160 Feather w/ Tag Connect

nRF9160 Feather w/ Tag Connect Connected

I highly recommend you jump SB47 on your nRF5340-DK with some solder. This forces the debugger to think an external devices is permanently connected. If you're only doing external debugging, this is very useful.

nRF5340-DK jumper highlighted

After hooking things up, It's time to do a quick smoke test. Running nrfjprog -r in a terminal should show this result:

$ nrfjprog -r
Applying system reset.
Run.

Success!

Note: these pictures are with an early version of the nRF9160 Feather. The procedure is the same. The orientation of the Tag-Connect though is horizontal not vertical as seen in the pictures.

Securing the Bootloader

In order to deliver secure over the air updates we need to generate our own signing key. Here's the (simplified) process:

  • Change directories to /opt/nordic/ncs/v1.x.x/bootloader/mcuboot
  • Run the image generation script:
scripts/imgtool.py keygen -k your-key-rsa-2048.pem -t rsa-2048
  • Create a mcuboot.conf file in your app with the included contents:
CONFIG_BOOT_SIGNATURE_TYPE_RSA=y
CONFIG_BOOT_SIGNATURE_KEY_FILE="your-key-rsa-2048.pem"
  • In CMakeLists.txt add the following lines:
# MCUboot related
list(APPEND mcuboot_OVERLAY_CONFIG
  "${CMAKE_CURRENT_SOURCE_DIR}/mcuboot.conf"
  )

Then start a pristine build using west:

west build -b circuitdojo_feather_nrf9160ns -p

A pristine build  should happen before releasing that way the version data is up to date in the app_update.binIt's critical not to lose your-key-rsa-2048.pem as it's the key for (secure) OTA updates to succeed.

Programming with the nRF5340-DK

Programming with the nRF5340-DK is straight forward in Zephyr using west. Here's what it looks like:

west build -b circuitdojo_feather_nrf9160ns -p
west flash --runner nrfjprog
nrfjprog -r

In the above, i'm:

  1. Doing a pristine build of my application with the nRF9160 Feather as the target.
  2. Then flashing using the nrfjprog runner option. This is preferred for all J-Link boards.
  3. Resetting the board using nrfjprog -r. As of this writing, west does not reset the board after programming.

Getting a modem trace

Sometimes, you may be requested to get a modem trace of your device. This section will focus on helping you get one for your nRF9160 Feather.

In order to get a modem trace, the TX and RX pins on your board need to be free. You'll also need a UART to USB adapter of some type. I used an FTDI one that has each of the lines broken out.

  1. First, set your prj.conf to include the following lines:

    # Enable modem trace
    CONFIG_BSD_LIBRARY_TRACE_ENABLED=y
    
    
    # AT host library
    CONFIG_UART_INTERRUPT_DRIVEN=y
    CONFIG_AT_HOST_LIBRARY=y
    

    Note: version v1.5.x and newer uses this flag to enable modem tracing: CONFIG_NRF_MODEM_LIB_TRACE_ENABLED=y

  2. Then, create a folder in your project/sample called boards and add a new file called circuitdojo_feather_nrf9160ns.overlay We'll want to enable the UART1 interface on pins 23 and 24 like below:

    /*
    * Copyright (c) 2020 Circuit Dojo LLC
    *
    * SPDX-License-Identifier: Apache-2.0
    */
    
    &uart1 {
    status = "okay";
    current-speed = <115200>;
    tx-pin = <24>;
    rx-pin = <23>;
    };
    
  3. Connect your USB to UART adatper. I've used clips from my logic analyzer to hold the wires in place. Connect the yellow wire to the TX on the board. Connect the orange wire to the RX on the board.

    img/programming-and-debugging/Screen_Shot_2020-09-16_at_4.42.58_PM.png

  4. Then, inside LTE link monitor enable the process with:

    AT%XMODEMTRACE=1,2
    AT+CFUN=0
    

    This will perpetually save and keep modem traces on.

    Note: this step is no longer necessary.

  5. Then open the serial port in the modem trace App and click start.

    img/programming-and-debugging/Screen_Shot_2020-09-16_at_4.47.06_PM.png

  6. Then run your app as normal. You should see the Trace size go up little by little as connections are made, etc.

    img/programming-and-debugging/Screen_Shot_2020-09-16_at_5.12.48_PM.png

  7. Then grab the file according to the log output. For example: Tracefile created: /Users/jaredwolff/Library/Application Support/nrfconnect/pc-nrfconnect-tracecollector/trace-2020-09-16T20-47-19.741Z.bin

    For more information, check out Nordic's original article on the subject.

Debugging in Visual Code

Debugging your application is possible with Visual Code. You will need a J-Link programmer and a Tag Connect (TC2030-CTX-NL) cable for this process. Programmers include the nRF9160 DK, nRF532 DK, J-Link EDU (if your project is non-profit) and the standard commercial J-Link programmers.

Here's the process:

  1. Download and install your version of the nRF Command Line Tools

  2. Install the C/C++ Extension and the Cortex-Debug extensions. They're both very handy in development and debugging of Zephyr based projects. C/C++ Extension Cortex M Debug Extension

  3. If you don't have one already, create a .vscode folder in the root of your project. .vscode Fodler

  4. Create a file called launch.json. This is where we'll set up the configuration for debugging.

  5. Here's a real example of a config I was using to debug a project in OSX:

    {
      // Use IntelliSense to learn about possible attributes.
      // Hover to view descriptions of existing attributes.
      // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
      "version": "0.2.0",
      "configurations": [
        {
          "name": "Cortex Debug",
          "cwd": "${workspaceRoot}",
          "executable": "${workspaceRoot}/pyrinas/applications/application/build/zephyr/zephyr.elf",
          "request": "launch",
          "type": "cortex-debug",
          "servertype": "jlink",
          "device": "nrf9160_xxAA",
          "interface": "swd",
          "armToolchainPath": "/Users/jaredwolff/gcc-arm-none-eabi-9-2019-q4-major/bin"
        }
      ]
    }
    

    For folks on Windows you'll have to modify appropriately:

    {
     // Use IntelliSense to learn about possible attributes.
     // Hover to view descriptions of existing attributes.
     // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
        {
            "name": "Cortex Debug",
            "cwd": "${workspaceRoot}",
            "executable": "${workspaceRoot}\\nrf9160-feather\\samples\\blinky\\build\\zephyr\\zephyr.elf",
            "request": "launch",
            "type": "cortex-debug",
            "servertype": "jlink",
            "device": "nrf9160_xxAA",
            "interface": "swd",
            "armToolchainPath": "C:\\Program Files (x86)\\GNU Tools Arm Embedded\\9 2019-q4-major\\bin"
        }
     ]
    }
    

    Remember that workspaceRoot refers to the folder you have opened in VSCode. This will most likely be C:\Users\<your username>\ncs\v1.5.0\nfed\. (/opt/nordic/ncs/v1.5.0 for Mac) You will have to modify the "executable" entry to match the path of your zephyr.elf file.

  6. Change the executable path and the armToolchainPath to reflect your system. Make sure you point the executable option to the .elf file that gets produced during the compilation process.

  7. Next, go to your projects prj.conf and disable the bootloader by commenting out CONFIG_BOOTLOADER_MCUBOOT=y or changing the y to a n. As of this writing, disabling the bootloader is required as it prevents the debugging process from occuring.

  8. In prj.conf you'll also want to enable the CONFIG_DEBUG option. This disables compiler optimizations which makes the debug process hairy or impossible.

  9. Finally, program your project using west build && west flash

  10. At this point, if you've ever done any debugging in Visual Code, you should be able to follow the final steps to debug your application!

  11. Set some breakpoints in your code by pressing the line number you want. A red dot will appear where the breakpoint is set. Breakpoint

  12. Start debugging by clicking the debug icon on the left. Then click the play button in the top left. Debug menu Debug play button

  13. You can use the popup menu on the right to control traversal through your code. Popup debug control

Managing Modem Firmware

Modem Firmware Update over UART

This sample can be used to load new modem firmware to your device using the bootloader only. This is useful if you do not have a programmer!

Setup

Make sure you have the VSCode plugin installed and running. Here are the instructions for each major architecture:

Get the modem firmware

Get your modem firmware of choice by nagivating to the nRF9160 Download page and scrolling to the nRF9160 SiP modem firmware section:

Download page

Download the version you'd like to use.

IMPORTANT: currently nRF9160 Feather is shipped with version 1.2.3 of the modem firmware. If you upgrade > v1.3.0 you cannot downgrade according to Nordic.

Build

Build the sample located in samples/mfw_update targeting circuitdojo_feather_nrf9160_ns.

Building sample complete Building sample complete

Loading

Then load to your device:

Loading Load complete

Running Python script

First you need to install the dependencies by running the following within samples/mfw_update/:

pip3 install -r requirements.txt

With python installed you should be able to run the corresponding update_modem.py script easily:

python3 update_modem.py mfw_nrf9160_1.3.0.zip /dev/tty.SLAB_USBtoUART 1000000

Note: update_modem.py is located in NFED under the nfed/samples/mfw_update/ path.

Here's what it should look like at the end of the process.

Upload complete

Confirming

You can confirm you have the version you loaded by running the AT+CGMR AT Command using at_client:

The AT host sample started
> AT+CGMR
mfw_nrf9160_1.3.0
OK

Modem Firmware Update with Programmer

Your modem firmware plays an important role in the nRF9160. The easiest way, as of this writing, to update is to use the Programmer's Update modem function. It's important to note that not all firmware is certified to work on every provider. For a full up-to-date list, check out Nordic's documentation.

Another note: you will need a programmer and Tag Connect cable in order to update the modem firmware.

Here are the instructions for updating your modem firmware:

  1. Download the modem firmware you need.
  2. Next, open up the Programmer in nRF Connect For Desktop. (You may need to open it first)
  3. Then open up a connection to your programmer. (Your programmer should be connected to USB and attached to your nRF9160 Feather) Port choices
  4. Once opened, the program will read the memory contents of your device and display it. Reading non-volatile mem
  5. To update the modem firmware, scroll down to the bottom right and click Update modem Update modem button
  6. Find your modem firmware Find modem firmware
  7. Start the DFU process by clicking Write! Start the process

Then, your device will be updated. This process takes about 45 seconds. You can check if the firmware version using the AT+CGMR AT command. Devices running on Verizon must use modem firmware v1.1.2.

nRF Connect For Desktop

nRF Connect For Desktop

nRF Connect For Desktop is the utility that you can use to manipulate your nRF9160 Feather. In this section we'll be focusing on two apps that will affect you the most:

  1. LTE Link Monitor
  2. Programmer

You can find the download page for nRF Connect For Desktop here.

Linux usesr: nRF Connect for Desktop is distributed as an appimage. Right click and enable running as an executable. Then you can double click and run as any other app.

Appimage Execute nRF Connect Desktop running on Ubuntu

LTE Link Monitor

The best way to debug anything cellular-related is to use the LTE Link Monitor.

To install:

  1. (for OSX folks) If you haven't already, install the Si2102 USB-to-Serial drivers.
  2. Install nRF Connect For Desktop app
  3. Open it up and in the list of apps find LTE Link Monitor
  4. Click install
  5. Once installed click open and let the fun begin! nRF Connect For Desktop with LTE Link Monitor installed

For more information check out Nordic's Documentation.

Using with LTE Link Monitor

Almost any code example can be used with the AT Host Library. Generally all that is needed is adding these lines to your prj.conf:

# AT host library
CONFIG_AT_HOST_LIBRARY=y
CONFIG_UART_INTERRUPT_DRIVEN=y

Alternatively, for a quick start, simply program the at_client example to your nRF9160 Feather. Then follow these quick steps to get up an running:

  1. Insert your SIM into the nRF9160 Feather.
  2. Attach your LTE antenna.
  3. Plug your nRF9160 Feather into your computer's USB port.
  4. Ensure that Flow Control is turned off, and Show only supported devices. is also unchecked. Flow Control unchecked
  5. Connect to it using the Device dropdown in the top left hand corner of the LTE Link Monitor. Devices dropdown On *nix based systems, the port will show up like /dev/tty.SLAB_USBtoUART. On Windows, you'll have to determine which COM port is associated by using the device manager.
  6. With Automatic requests turned on and the nRF9160 Feather connected, press the AT+CFUN=1 button followed by the AT+CFUN? button. This will cause a few important commands to be automatically sent to your nRF9160 Feather. Additionally, your nRF9160 Feather will attempt to connect to the closest compatible tower possible.
  7. Review the LTE Link Monitor for connection information. LTE Link Monitor connected Yes, the LTE Link Monitor provides some great information. Consider it your go-to tool when debugging cellular or board related issues.

Programmer

The programmer is excellent for updating your application firmware. The most important function it provides is updating the modem firmware.

Updating Application Firmware

Another way of programming your application other firmware images is to use the nRF Connect For Desktop Programmer App.

  1. First, you'll need to install it if you haven't already.
  2. Then open it up and select your programmer Port choices
  3. Then add a hex file using the button on the right side. Add a hex file
  4. Click Browse to loook for your file Add a hex file
  5. Browse your Nordic Connect SDK repo for your file. For instance the at_client hex image is: ncs/nrf/samples/nrf9160/at_client/build/zephyr/merged.hex Add a hex file
  6. Hit write to start the writing process. Remember your programmer has to be connected to the nRF910 Feather for this to work! Add a hex file

Handy trick! Since the nRF Connect For Desktop app is web based, you can use (Command) ⌘ + R to refresh the program. (or CTRL + R on Windows/Linux) This is great when the app goes into a weird state or if your serial device/programmer is now showing up.

Debug Serial Usage

The nRF9160 Feather comes with an on-board Silicon Labs CP2102 USB-to-UART chip. You can use it with most serial terminal viewers. If you have an older version of Windows you will have to install the driver. The download is located here.

Here's some recommendations for software to communicate with the nRF9160 Feather. No matter what program you use, the standard baud rate for the console is 115200. All other options are standard/default (8 bits, oon-pairty, 1 stop bit).

zephyr-tools-monitor

zephyr-tools-monitor comes with the Zephyr Tools VSCode Plugin. Here is the help dialog:

❯ zephyr-tools-monitor --help
App
USAGE:
  app [OPTIONS]
FLAGS:
  -h, --help            Prints help information
OPTIONS:
  --list, -l            Lists serial ports avaiable
  --follow,             Follow serial port if it disconnects
  --port,               Port to connect to
  --baud,               Baud to use (default 115200)
ARGS:
  <INPUT>

Typical usage includes:

  • List all available ports use:

    ❯ zephyr-tools-monitor -l
    ["/dev/tty.URT2","/dev/tty.URT1","/dev/tty.BLTH","/dev/tty.Bluetooth-Incoming-Port","/dev/tty.usbmodem0009600833633","/dev/tty.usbmodem0009600833631","/dev/tty.usbmodem0009600833635","/dev/tty.SLAB_USBtoUART","/dev/tty.usbserial-14530"]⏎  
    
  • A typical connection attempt:

    ❯ zephyr-tools-monitor --port /dev/tty.SLAB_USBtoUART --follow
    

If you'd like to download zephyr-tools-monitor standalone you can do so by downloading the pre-built binary here.

nRF Connect For Desktop - LTE Link Monitor

If you haven't already, make sure you check out the LTE Link Monitor. It's a great multi-purpose tool for using and debugging the nRF9160 Feather.

CoolTerm

CoolTerm

CoolTerm has been my go-to for testing and debugging. Fortunately it's also multi-platform! You can download it by going here: https://www.freeware.the-meiers.org

Example Code

Examples

Examples

All examples can be found in the nRF9160 Feather Examples and Drivers (nFED) repository. You can install it during the setup process. Here are some links to setting up on different platforms:

All samples are in nfed/samples (or nfed/samples depending on how you set everything up). They include:

  • accelerometer - for a basic onboard accelerometer demo
  • at_client - for testing connections using LTE Link Monitor (📶 requires SIM if you want to connect to LTE/NB IoT)
  • battery - for a basic onboard battery measurement demo
  • blinky - for a basic led blink demo
  • bme280 - for an example of using the bme280 on i2c
  • button - for a basic example using the onboard mode button
  • deep_sleep - ultra deep sleep mode demo
  • external_flash - external flash demo
  • external_rtc - using onboard RTC demo
  • gps - basic gps demo (📶 requires SIM if you want to connect to LTE/NB IoT to retreive SUPL data)
  • sms - basic SMS demo (📶 requires SIM to send SMS)

Most of these examples are based from the nRF Connect SDK (either directly from Nordic or Zephyr)

More examples coming soon!

Building and loading using VSCode

Using the command window run Zephyr Tools: Build

Build

Then place the device into bootloader mode:

  1. Hold the MODE button
  2. Then tap the RST button while holding mode
  3. Hold the MODE button until the Blue LED illuminates

Then, load using the Zephyr Tools: Load via Bootloader task.

Option for loading

Pay attention to the progress in the bottom console.

Option for loading

Once complete, the extension will reset your device and should start executing!

Important: make sure you close all console sessions with your nRF9160 Feather before programming using newtmgr. Otherwise the newtmgr image upload will timeout.

Building Manually

To build an example,

  1. Install and setup the VSCode Extension for your OS:
    1. Windows
    2. Mac
    3. Linux
  2. With the extension installed and setup, navigate to the sample you want in a VSCode terminal and run:
west build -b circuitdojo_feather_nrf9160ns

Here's an example of output when finished:

west build -b circuitdojo_feather_nrf9160ns

...

-- Configuring done
-- Generating done
-- Build files have been written to: /Users/jaredwolff/Git/nrf-connect/ncs/nrf/samples/nrf9160/at_client/build
[0/180] Performing build step for 'spm_subimage'
[151/155] Linking C executable zephyr/zephyr_prebuilt.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       32256 B        48 KB     65.62%
            SRAM:        5488 B        64 KB      8.37%
        IDT_LIST:          40 B         2 KB      1.95%
[155/155] Linking C executable zephyr/zephyr.elf
[2/176] Performing build step for 'mcuboot_subimage'
[248/253] Linking C executable zephyr/zephyr_prebuilt.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       42500 B        48 KB     86.47%
            SRAM:       26800 B        64 KB     40.89%
        IDT_LIST:          72 B         2 KB      3.52%
[253/253] Linking C executable zephyr/zephyr.elf
[163/176] Linking C executable zephyr/zephyr_prebuilt.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       76868 B     441856 B     17.40%
            SRAM:       36928 B       128 KB     28.17%
        IDT_LIST:         120 B         2 KB      5.86%
[174/174] Generating zephyr/merged.hex

Note: having trouble building? Make sure you check out the troubleshooting page.

Programming can be completed with newtmgr:

newtmgr -c serial image upload build/zephyr/app_update.bin

Note you always want to use the app_update.bin when using newtmgr. These binaries are also used for FOTA and are always located in your_sample/build/zephyr/.

During testing, it's recomended to use the LTE Link Monitor whenever you need to manually test or execute commands.

nRF Cloud AGPS Sample

Important: this sample is outdated and no longer exists in future versions of nRF Connect SDK

The nrf_cloud_agps sample is the easiest way to get started with generating GPS coordinates with your nRF9160 Feather.

Precompiled Binary

Note: you can get a pre-build binary file compiled previously using NCS v1.3.2 here.

Programming nrf_cloud_apgs Sample

  1. Change directories to ncs/nrf (Make sure you're using NCS v1.4.0 or newer.)
  2. Then change directories to /nrf/samples/nrf9160/agps/
  3. Add this to prj.conf:
    # Cloud prefix for nRF9160 Feather
    CONFIG_NRF_CLOUD_CLIENT_ID_PREFIX="feather-"
    
    # Image manager
    CONFIG_IMG_MANAGER=y
    CONFIG_FLASH=y
    CONFIG_IMG_ERASE_PROGRESSIVELY=y
    
    # Enable Zephyr application to be booted by MCUboot
    CONFIG_BOOTLOADER_MCUBOOT=y
    
    # COEX0 is used to enable the GPS LNA, but it has to be configured to do so.
    CONFIG_NRF9160_GPS_SET_COEX0=y
    CONFIG_NRF9160_GPS_COEX0_STRING="AT%XCOEX0=1,1,1565,1586"
    

Then compile as normal:

west build -b circuitdojo_feather_nrf9160ns

Note: having trouble building? Make sure you check out the troubleshooting page.

Then load using newmgr:

newtmgr -c serial image upload build/zephyr/app_update.bin
newtmgr -c serial reset

Setting Up nRF Connect for Cloud

During factory test, your nRF9160 Feather is added to nRF Connect for Cloud for your immediate use! The only thing you'll need, other than your nRF9160 Feather, SIM and antenna is your getting started card:

Cloud Code

Every nRF9160 Feather has a device ID generated based on the IMEI. Your full device ID will look something like:

feather-<IMEI> where <IMEI> is the IMEI tied to your specific device.

Note: You can get the IMEI by running the AT+CGSN=1 command in LTE Link Monitor while running the at_client, default factory firmware or other firmware with AT Commands turned on.

Here are the steps to get you the rest of the way.

  1. First, program your device with the nrf_cloud_agps sample.
  2. Then, power up and confirm that the device can connect to the cloud.
  3. Create an nRF Connect for Cloud Account Add new device
  4. Once created, go to the top left and click the big + icon. Add LTE device
  5. Then skip the iBasis setup since we're using Hologram. Skip iBasis
  6. Enter the Device ID and the PIN provided on your card. Enter device ID and pin
  7. Once you press Add Device, nRF Connect for Cloud should notify you that your device has been added!
  8. Navigate to Devices and click on the device you're working wtih! Devices

That's it!

Your device screen will adapt to the example code that you're using. For example, it should display a map when you begin to publish GPS data.

nRF Connect for Cloud Screenshot with map

Troubleshooting

There are some things that can go wrong here. They're usually related to your nRF Cloud certs.

Reloading the certs can be done using the tutorial here.

AT Client Sample

Important: these instructions are outdated and no longer apply for NCS > v1.5.x.

Precompiled Binary

Note: you can get a pre-build binary file compiled using v1.3.2 here.

Instructions

Change directories to ncs/nrf/samples/nrf9160/at_client. Then compile as shown beffore in the example code section of this guide.

Before you do compile make sure that the following lines are added to the prj.conf:

# Enable Zephyr application to be booted by MCUboot
CONFIG_BOOTLOADER_MCUBOOT=y

This will enable support for the bootloader. Then, build using the build command:

west build -b circuitdojo_feather_nrf9160ns

...

-- Configuring done
-- Generating done
-- Build files have been written to: /Users/jaredwolff/Git/nrf-connect/ncs/nrf/samples/nrf9160/at_client/build
[0/180] Performing build step for 'spm_subimage'
[151/155] Linking C executable zephyr/zephyr_prebuilt.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       32256 B        48 KB     65.62%
            SRAM:        5488 B        64 KB      8.37%
        IDT_LIST:          40 B         2 KB      1.95%
[155/155] Linking C executable zephyr/zephyr.elf
[2/176] Performing build step for 'mcuboot_subimage'
[248/253] Linking C executable zephyr/zephyr_prebuilt.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       42500 B        48 KB     86.47%
            SRAM:       26800 B        64 KB     40.89%
        IDT_LIST:          72 B         2 KB      3.52%
[253/253] Linking C executable zephyr/zephyr.elf
[163/176] Linking C executable zephyr/zephyr_prebuilt.elf
Memory region         Used Size  Region Size  %age Used
           FLASH:       76868 B     441856 B     17.40%
            SRAM:       36928 B       128 KB     28.17%
        IDT_LIST:         120 B         2 KB      5.86%
[174/174] Generating zephyr/merged.hex

Note: having trouble building? Make sure you check out the troubleshooting page.

You can see towards the end of this output that both the application and the bootloader have been built and merged.

Programming can be completed with newtmgr:

newtmgr -c serial image upload build/zephyr/app_update.bin

During testing, it's recomended to use the LTE Link Monitor whenever you need to manually test or execute commands.

Low Power Operation

In most examples when your device goes idle, it will go into a sleep mode automatically. In the best case,

  1. v5 boards draw about:

    • 4 uA via 3.6V Vbat at room temp
  2. v4 boards draw about:

    • 30µA via 3.3V Vbat at room temp.
    • 28µA via 3.6V Vbat at room temp.

Optimizing for low power does take some extra work to make sure all sources of current draw are turned off. The active sleep sample in NFED does this for you.

If you'd like to optimize manually, here are some important steps to getting low power.

  1. Remove all connections to SWD programmer

  2. Set your prj.conf to match these values

    # Stacks and heaps
    CONFIG_MAIN_STACK_SIZE=4096
    CONFIG_HEAP_MEM_POOL_SIZE=16384
    
    CONFIG_GPIO=y
    CONFIG_I2C=y
    CONFIG_SPI=y
    CONFIG_DEBUG=n
    
    # Add the accelerometer
    CONFIG_SENSOR=y
    CONFIG_LIS2DH=y
    
    CONFIG_CONSOLE=n
    CONFIG_UART_CONSOLE=n
    CONFIG_SERIAL=n
    
    # Zephyr Device Power Management
    CONFIG_DEVICE_POWER_MANAGEMENT=y
    CONFIG_PM=y
    
    # Network
    CONFIG_NETWORKING=y
    CONFIG_NET_SOCKETS=y
    CONFIG_NET_NATIVE=n
    CONFIG_NET_SOCKETS_POSIX_NAMES=y
    
    # Modem 
    CONFIG_NRF_MODEM_LIB=y
    
    # Enable Zephyr application to be booted by MCUboot
    CONFIG_BOOTLOADER_MCUBOOT=y
    

    Importantly the accelerometer needs to be enabled and CONFIG_SERIAL MUST be set to =n. This turns off all console/debug output to the USB to UART chip.

  3. In an boards/circuitdojo_feather_nrf9160ns.overlay define the following:

    &i2c1 {
      lis2dh@18 {
          compatible = "st,lis2dh";
          label = "LIS2DH";
          reg = <0x18>;
          irq-gpios = <&gpio0 29 GPIO_ACTIVE_HIGH>, <&gpio0 30 GPIO_ACTIVE_HIGH>;
          disconnect-sdo-sa0-pull-up;
      };
    };
    

    disconnect-sdo-sa0-pull-up saves about 130µA during sleep as it disables a Pull-Up within the LIS2DH12TR that is connected to the grounded SDO pin.

If you only have one thread running you can put the device into idle this way:

while (1)
{
k_cpu_idle();
}

Examples like the Asset Tracker will manage this state for you.

Compatible Cloud

The nRF9160 Feather is compatible a handful of cloud providers and the list is growing!

Hosted

Self Hosted

Cellular Provider Matrix

Cellular

In order to use a provider below you'll likely have to set the PDP context. For NCS >= 1.7.x you can set it in your prj.conf using the following config variables:

CONFIG_PDN=y
CONFIG_PDN_DEFAULTS_OVERRIDE=y
CONFIG_PDN_SYS_INIT=y
# Note: "ip" is set by PDN_DEFAULT_FAM kconfig's
# example:
# AT+CGDCONT=1,"ip","apn" - below only sets APN field
CONFIG_PDN_DEFAULT_APN="myapn"
CONFIG_PDN_DEFAULT_FAM_IPV4V6=y

(The above example is from Nordic's Devzone.)

There are also other configuration options like setting the authentication method, user name and password:

choice
	prompt "Authentication method"
	default PDN_DEFAULT_AUTH_NONE

config PDN_DEFAULT_AUTH_NONE
	bool "None"
config PDN_DEFAULT_AUTH_PAP
	bool "PAP"
config PDN_DEFAULT_AUTH_CHAP
	bool "CHAP"
endchoice

config PDN_DEFAULT_AUTH
	int
	default 0 if PDN_DEFAULT_AUTH_NONE
	default 1 if PDN_DEFAULT_AUTH_PAP
	default 2 if PDN_DEFAULT_AUTH_CHAP

config PDN_DEFAULT_USERNAME
	string "Username"
	depends on !PDN_DEFAULT_AUTH_NONE

config PDN_DEFAULT_PASSWORD
	string "Password"
	depends on !PDN_DEFAULT_AUTH_NONE

For NCS < 1.6.x, this can be done in your project's prj.conf in Zephyr. Here's an example of setting the PDP context to use Hologram.

# Set the PDP context
CONFIG_LTE_LINK_CONTROL=y
CONFIG_LTE_PDP_CMD=y
CONFIG_LTE_PDP_CONTEXT="0,\"IP\",\"hologram\""

Simply replace hologram with a provider specific APN and you'll be good to go.

Some providers also require a username and password. For example, here's what Soracom's looks like:

CONFIG_LTE_PDN_AUTH_CMD=y
CONFIG_LTE_PDN_AUTH="0,\"PAP\",\"sora\",\"sora\""

Side note: in the case of both Hologram an Soracom you do not need the PDP context to transfer data.

Here's a full working list of what plays nicely with the nRF9160 Feather. This list is subject to change at any time.

LTE

Provider NameConnected ToNotesWorkingAPN
HologramSprint/AT&T/T-MobileThe first SIM to get working out of the box. Also supports T-Mobile and Verizon connections. Coverage info.hologram
SoracomAT&T/T-MobileWorking great from Circuit Dojo HQ. More info on coverage here.soracom.io
VerizonVerizonUse Verizon ThingSpace to get starte quickly.
Twilio (Super Sim)T-Mobile and othersNordic indicates modem firmware 1.3.0 supports Twilio's Super Sim🔶super
AT&TAT&TTested indirectly via other MVNOs.🔶

Note: are some important caveats about Verizon. That information is located here.

NB IoT

Provider NameConnected ToNotesWorkingAPN
Twilio (Standard Narrowband)T-MobileT-Mobile does not support the nRF9160. This is subject to change.🔴

Emoji usage chart:

EmojiNote
Tested and working
🔶In progress
🔴Tested. Does not work!

💡Side note: unless otherwise noted these are tested along the shoreline of Connecticut. Your mileage may vary so make sure you do your own testing before adopting a provider.

Customer reports

We don't always have the ability to test every single cellular provider. In this section, here are a few providers that customers have reported success with.

Provider NameConnected ToNotesAPN
Teal?In Canada (https://www.tealcom.io)teal

For the latest information on which providers support the nRF9160 SiP check out Nordic's nRF9160 certification page.

Downloads

Downloads

Hardware Related

TypeDonwload Link
DocumentationLink to Github
HardwareLink to Github
Bill of MaterialsLink to Aligni
3D ModelLink to Github
EnclosureLink to Grabcad

Software Related

TypeDonwload Link
Pre-compiled SamplesLink
Bootloader (v1)Link
Bootloader (v2)Link
newtmgr CLI (v1)Link
Board Defintions (v1.3.x)link
Board Definitions (v1.2.x)link

Manual downloads of NCS

Manual downloads of NCS (including minimal version) are hosted here: https://developer.nordicsemi.com/.pc-tools/toolchain

License

All hardware related files are available under the CERN v1.2 license. Click here for more details.

All documentation is released under a Creative Commons Share-alike license. Click here for more details.

Any applicable software is released under the Apache 2.0 license. Click here for more details.

Compliance

Compliance

To make things easier for you, the nRF9160 Feather comes pre-tested and ready for integration. All applicable testing will be done to ensure comppliance with FCC and CE EMI/EMC requirements. See each section below for more information.

Open Source Hardware Certification:

OSHW

CE Compliance

Current status: Compliant

FCC Part15 Compliance

Current status: Compliant

ISED (IC) Compliance

Current status: Compliant

Verizon Network Certification

Current status: Certified

FCC Pre-certification and Markings

When designing the nRF9160 Feather into your own projects, there are some marking requirements. Per the instructions from Nordic, you must have this written on your product somewhere:

  • Contains FCC ID: 2ANPO00NRF9160
  • Contains IC: 24529-NRF9160

Additionally, the nRF9160 Feather must be used at a minimum of 20 cm (7.87 inches) from the body at all times. This means the nRF9160 Feather should not worn on the body without sufficent isolation.

Country of Origin

  • Assembled in the USA 🇺🇸
  • Circuit boards fabricated in Taiwan 🇹🇼

Verizon operation

Versions of the nRF9160 Feather < v4 are supported on Verizon. If you've been chomping at the bit to get running on their newtwork, here's your chance!

Requirements

There are some requirements related to the use of Verizon's network. Here are the details:

  1. You must use Modem Firmware v1.1.2. The v1.2.x branch of the modem firmware is not supported (and will never be supported) on Verizon. You can check what version of the Modem Firmware you're running by executing this AT command: AT+CGMR. It will print something similar to nrf9160_1.1.2 Note: if you're running an older version of modem firmware you may have to use the %SHORTSWVER command.

    If you're not on 1.1.2 make sure you update using the guide here.

  2. For production deployments, you must use the 1.2.x branch of the nRF Connect SDK.

  3. If you've purchased a genuine nRF9160 Feather, your IMEI will already be added to Verizon's network. To get started, create a Verizon ThingSpace account. There you'll be able to create a new line with your nRF9160 Feather's IMEI.

    You can get your IMEI by running the AT+CGSN=1 command. The reply should look someting like this:

    AT+CGSN=1
    +CGSN: "352656100367872"
     OK
    
  4. Finally, any device on Verizon's network must be running the LWM2M Carrier Library. This allows Verizon to update the modem firmware in the event it's necessary. Enabling the LWM2M carrier library is as simple as adding CONFIG_LWM2M_CARRIER=y to your prj.conf.

Troubleshooting

This page has a list of common problems and solutions realated to the nRF9160 Feather.

Compiling Problems

Getting a west.manifest.ManifestImportFailed when building on Mac

Make sure that you've installed Xcode Command Line tools using xcode-select --install

Programming problems

The nRF9160 Feather does nothing after being programmed/flashed.

After being programmed using west flash, you may have to issue an additional nrfjprog -r or hit the RST button on the board. This should start code execution.

GPS Connection issues

Unable to get a fix after waiting a long time. (Using the gps example.

If your nRF9160 Feather is plugged into USB, try a different USB power supply. During the testing of the nRF9160 Feather, I found that certain USB C-to-A adapters injected were not properly grounded. This lead to issues getting a fix or prevented it all together. This especially applied to Apple Macbooks.

"The toolchain is unable to build a dummy C file"

If you're trying to build an example and you're getting an error building your code your should delete the Cmake cache:

rm -rf ~/Library/Caches/zephyr

More info here: https://devzone.nordicsemi.com/f/nordic-q-a/55475/the-toolchain-is-unable-to-build-a-dummy-c-file

Also a post on the forum: https://community.jaredwolff.com/d/51-error-whilst-compiling-blinky/3

Debugging a Hard Fault

[00:00:07.098,754] <err> os: Exception occurred in Secure State
[00:00:07.105,346] <err> os: ***** HARD FAULT *****
[00:00:07.110,961] <err> os:   Fault escalation (see below)
[00:00:07.117,279] <err> os: ***** BUS FAULT *****
[00:00:07.122,833] <err> os:   Precise data bus error
[00:00:07.128,601] <err> os:   BFAR Address: 0x50008158
[00:00:07.134,582] <err> os: r0/a1:  0x00000000  r1/a2:  0x20021489  r2/a3:  0x20021490
[00:00:07.143,341] <err> os: r3/a4:  0xffffffff r12/ip:  0x00046f95 r14/lr:  0x0003ba81
[00:00:07.152,130] <err> os:  xpsr:  0x81000000
[00:00:07.157,379] <err> os: s[ 0]:  0x00000000  s[ 1]:  0x00000000  s[ 2]:  0x00000000  s[ 3]:  0x00000000
[00:00:07.167,938] <err> os: s[ 4]:  0x00000000  s[ 5]:  0x00000000  s[ 6]:  0x00000000  s[ 7]:  0x00000000
[00:00:07.178,466] <err> os: s[ 8]:  0x00000000  s[ 9]:  0x00000000  s[10]:  0x00000000  s[11]:  0x00000000
[00:00:07.188,995] <err> os: s[12]:  0x00000000  s[13]:  0x00000000  s[14]:  0x00000000  s[15]:  0x00000000
[00:00:07.199,523] <err> os: fpscr:  0x00000000
[00:00:07.204,772] <err> os: Faulting instruction address (r15/pc): 0x00047ba0
[00:00:07.212,768] <err> os: >>> ZEPHYR FATAL ERROR 0: CPU exception on CPU 0
[00:00:07.220,672] <err> os: Current thread: 0x20017d00 (unknown)
$ /opt/nordic/ncs/v1.5.0/toolchain/bin/arm-none-eabi-addr2line -e build/zephyr/zephyr.elf 0x00047ba0
reent.c:?

Error 3 from newtmgr

While programming via newtmgr you may run into problems programming your board via the bootloader:

newtmgr -c serial image upload build/zephyr/app_update.bin
63.70 KiB / 65.69 KiB [===================================================================================================================================================================================>-----]  96.98% 15.82 KiB/s
Error: 3

There are a few reasons for this incuding:

  • Make sure that you do not have your serial console open while transferring. This will case some data to drop during the application upgrade.

  • V1 versions of the nRF9160 Feather only work with older versions of the SDK (1.2.x ad 1.3.x). The solution here is to upgrade the bootloader.

    • Navigate to the downloads page and download the V2 bootloader
    • Attach your programming cable and board as you would in programming and debugging
    • Use nrfjprog (or similar) to load the file:
    nrfjprog --program bootloader.hex --chiperase
    

    Alternatively you can also downgrade SDK version but this is not supported.

  • For V1 bootloaders, newtmgr will not program images above 196kB. The solution here is to upgrade to the latest bootloader.

Support

The best place for support is the Circuit Dojo support forum. In most cases you'll recieve a response within 1-2 business days. For more information see our Terms of Service.

If you have a question relating to your order please contact support@jaredwolff.com

The nRF9160 Feather is licenced under the CERN Open Hardware Licence Version 2 - Weakly Reciprocal For more details on warranty and liability click here.

Purchase

The nRF9160 Feather has arrived! It's available at our store here:

Circuit Dojo Logo

It's also available on these great sites:

Digikey

GroupGets Logo

Tindie

Changelog

Hardware

v5 - (October 2022)

  • No longer supports complete shutdown mode
  • Using nRF9160 B1A variant
  • Now supports "buttonless" DFU mode
  • Now supports direct USB-C connection

Added:

  • Ferrite and 47u for power inputs
  • Additional bypass to match nRF9160 reference

Changed:

  • Relocated CP2102 closer to USB connector
  • Improved ground return paths
  • Pins reference nRF9160 pin numbers
  • Changed 47uf cap to 4.7u for B1 variant
  • Replaced Buck with TPS62840
  • Added jumper for disabling charger
  • Added current resistors for CC pins
  • Added connections to RESET and MODE pins to CP2102 for buttonless DFU mode entry
  • Moved SIM holder
  • Re-routed battery measurement circuit
  • Replace charger with BQ25170JDSGR and updated supporting passives

Removed:

  • Reference designators

v4 - (October 2021)

Changed:

  • Changed power supply to use TI's LM3281
  • USB connector to USB-C
  • Changed schottky diode part to make more room for USB-C
  • Updated 3D render
  • Renamed LNA_EN to GPS_EN to avoid confusion
  • Charging LED fed by 5V
  • Replaced battery charger with Microchip MCP73830T
  • Improved/cleaned up power and return paths
  • INT1 is now an optional jumper

Added:

  • Added INT2 connection for accelerometer with closed jumper
  • A0 and MODE pin of LM3281 connected for PWM/PFM control

v3 - (July 2021)

  • Fixed SCL/SDA labels
  • Added test points for SIM tests

v2 - (Jan 2021)

Backside of nRF9160 Feather V2

  • Added 3-axis Accelerometer by ST (LIS2DH12TR). Zephyr/nRF Connect SDK includes built-in support for this chip.
  • Added Accelerometer INT1 pin to Pin 2 on the board.
  • Added JMP1 to free up use for Pin 2 (INT1 pin on LIS2DH is push/pull an always on)
  • The power supply enable signal, which originally was inaccessible, is now available next to the TX pin.
  • Added JMP2 to disable PS_EN's connection to the power supply. "Always on" operation by shorting the middle and right pads on JMP2.
  • Updated the bottom side labels thanks to Sparkfun's Buzzard tool. They deserve all the credit there!

Software

NFED (nRF9160 Feather Examples and Drivers) - (Jan 2021)

  • Added accelerometer sample
  • Added bme280 sample

Documentation

Uncommitted

Changed

  • Changed note about compiling app
  • Changed instructions about installing nRF Connect Desktop
  • Fixed typo related to the bootloader-use section of Programming and Debugging
  • Updated bootloader moe instructions
  • Changed link to nRF53DK
  • Fixed various typos
  • Updated instructions for getting modem trace
  • Install insructions updated to 1.5.0
  • Adding entries to agps sample prj.conf

Removed

  • Video for putting device into bootloader mode (outdated)

Added

  • Added a page about compatible cloud infrastructures
  • Added some extra help related to newtgmr

Thanks 🙏

Special thanks to all who have helped make this project successful. Here are a few honorable mentions:

  • Thanks to all the kind folks at Nordic Semiconductor! Eeryone on Devzone to sales to the FAEs in the States have all been very supportive of the project. Thank you, thank you thank you!
  • Many thanks to the Aligni team for making a great product and helping open source projects succeed. You can sign up for you own account here.
  • Thanks to the team at Hologram team! Without you guys no one would have a SIM to connect their nRF9160 Feathers with!
  • Last, by not least, thanks to my main collaborators GroupGets and Hackster. Without them there wouldn't be a nRF9160 Feather to release into the world!

Archive

SDK Setup (Mac OS)

This page is all about getting your Mac compiling code for the nRF9160 Feather. Run into trouble during the process? Post your questions on the community forum.

Installing IDE

  1. Install or use the code editor of your choice. I personally use Microsoft Visual Studio Code. The download link is here
  2. If you decide to use Visual Studio Code, make sure you install the C/C++ and Cortex-Debug extentions using the built in extension marketplace.

Installing SDK

  1. Install Python3. The easiest way is with Homebrew. Install brew first, then open a terminal and run:

    brew install python3 git cmake ninja wget
    
  2. Once complete, check to make sure that python3 is installed. Here's the example output. (Your version may be different.)

    > python3 --version
    Python 3.8.6
    

    💡Note: if you've freshly installed Homebrew or get an error that python3 is not found, you may have to add /usr/local/bin to your PATH. For example here's an entry for .bash_profile or .zshrc:

    export PATH=/usr/local/bin/:$PATH
    

    For a shell like fish you'll need:

    set -U fish_user_paths /usr/local/bin/ $fish_user_paths
    
  3. Also check that git is installed with:

    ❯ git --version
    git version 2.27.0
    
  4. Install west. West is the most important utility for using nRF Connect SDK & Zephyr. You'll become quite familliar with very soon.

    pip3 install west
    

    💡Note: you can update west by issuing pip3 install -U west It will uninstall the version on your machine and replace it with the latest. (It won't do anything if you have the latest installed.)

  5. Now create a folder on your machine and call it nfed (short for nRF9160 Feather Examples and Drivers). Open a terminal to this folder and initialize nRF Connect SDK using west:

    cd ~
    mkdir nfed
    cd nfed
    west init -m https://github.com/circuitdojo/nrf9160-feather-examples-and-drivers --mr main
    
  6. Once your nRF Connect SDK compontents are downloaded, you'll need to fetch the remaining SDK:

    west update
    

    You'll see a bunch of output go by as west downloads dependencies using Git.

    Here's what your nfed folder should look like:

    ❯ tree -L 1
    .
    ├── bootloader
    ├── build
    ├── latest
    ├── mbedtls
    ├── modules
    ├── nrf
    ├── nrf9160-feather
    ├── nrfxlib
    ├── test
    ├── tools
    └── zephyr
    
  7. Install the remaining python3 requirements by running these commands in your nfed directory.

    pip3 install -r zephyr/scripts/requirements.txt
    

The ARM Embedded Toolchain

  1. Install the toolchain by pulling it from ARM. Run these commands:

    cd ~
    wget "https://developer.arm.com/-/media/Files/downloads/gnu-rm/9-2019q4/gcc-arm-none-eabi-9-2019-q4-major-mac.tar.bz2"
    tar xvfj gcc-arm-none-eabi-9-2019-q4-major-mac.tar.bz2
    rm gcc-arm-none-eabi-9-2019-q4-major-mac.tar.bz2
    

    Note for Catalina users you will get an error when running these utilities for the first time. You must allow them to be executed in your Security preferences.

    Error running ARM Toolchain

  2. Finally you'll need export a few important environment variables for things to work. For bash here's the entry for .bash_profile that I have:

    # Zephyr related
    export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
    export GNUARMEMB_TOOLCHAIN_PATH="~/gcc-arm-none-eabi-9-2019-q4-major"
    

    💡Note: this should also work for .zshrc for those folks who are using newer versions of Mac OS (or just plain prefer zsh)

    For folks using fish you're going to use:

    set -Ux ZEPHYR_TOOLCHAIN_VARIANT gnuarmemb
    set -Ux GNUARMEMB_TOOLCHAIN_PATH "~/gcc-arm-none-eabi-9-2019-q4-major"
    

newtmgr (Used to load your application via USB serial bootloader)

  1. For loading code to your nRF9160 Feather, you'll need to download and copy a custom version of newtmgr to a folder in your PATH.

    cd ~/Downloads
    wget "https://docs.jaredwolff.com/files/newtmgr/darwin/newtmgr.zip"
    unzip newtmgr.zip
    sudo mv newtmgr /usr/local/bin
    rm newtmgr.zip
    

    If you're not sure, /usr/local/bin/ is always a good spot for these types of binaries.

  2. Then you'll need to add your serial profile to make it easier to download/update your device:

    newtmgr conn add serial type=serial connstring='dev=/dev/tty.SLAB_USBtoUART,baud=1000000'
    

    If you have multiple Silicon Labs CP2102 connected to your machine your serial port may be named differently. I recommend you unplug all devices that could be named tty.SLAB_USBtoUART to ensure you're targeting the correct device during programming.

  3. Having trouble? You may have to install the drivers.

For more info in using newtmgr checkout the programming section of this documentation.

Testing it

You can quickly test if your SDK is set up correctly by checking out the samples.

SDK Setup (Windows)

This page is all about getting your Windows machine compiling code for the nRF9160 Feather. Run into trouble during the process? Post your questions on the community forum.

IDE Setup

  1. Install or use the code editor of your choice. I personally use Microsoft Visual Studio Code. The download link is here
  2. If you decide to use Visual Studio Code, make sure you install the C/C++ and Cortex-Debug extentions using the built in extension marketplace. Extensions installed

SDK Install

  1. Install the Chocolatey (choco) package manager. In the start menu type cmd then right click and open with Administrative Privledges.

    Powershell w/ Admin

  2. Then paste the install script and press enter:

    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
    

    For more info check out this page.

  3. Now, lets install the remaining deps we'll need for Zephyr/nRF Connect using choco. In a new cmd.exe session (with Administrator privledges) run:

    choco feature enable -n allowGlobalConfirmation
    choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' --version 3.18.5
    choco install ninja gperf python git
    
  4. Next install west using pip. West is the most important utility for using nRF Connect SDK & Zephyr. You'll become quite familliar with very soon.

    pip install west
    

    💡Note: you can update west by issuing pip3 install -U west It will uninstall the version on your machine and replace it with the latest. (It won't do anything if you have the latest installed.)

  5. Now create a folder on your machine and call it nfed (short for nRF9160 Feather Examples and Drivers). For windows it's best to put it in C:\. Open a new cmd.exe prompt in this folder and initialize nRF Connect SDK using west:

    cd C:\
    mkdir nfed
    cd nfed
    west init -m https://github.com/circuitdojo/nrf9160-feather-examples-and-drivers --mr main
    
  6. Once your nRF Connect SDK compontents are downloaded, you'll need to fetch the remaining SDK:

    west update
    

    You'll see a bunch of output go by as west downloads dependencies using Git. (This will take hot minute so make sure you're prepared with something else to do. 😬)

    Here's what your nfed folder should look like:

    C:\nfed>dir
     Volume in drive C has no label.
     Volume Serial Number is B013-63F8
    
     Directory of C:\nfed
    
    10/27/2020  12:25 PM    <DIR>          .
    10/27/2020  12:25 PM    <DIR>          ..
    10/27/2020  12:22 PM    <DIR>          .west
    10/27/2020  12:24 PM    <DIR>          bootloader
    10/27/2020  12:25 PM    <DIR>          mbedtls
    10/27/2020  12:27 PM    <DIR>          modules
    10/27/2020  12:22 PM    <DIR>          nrf
    10/27/2020  12:22 PM    <DIR>          nr9160-feather
    10/27/2020  12:24 PM    <DIR>          nrfxlib
    10/27/2020  12:24 PM    <DIR>          test
    10/27/2020  12:26 PM    <DIR>          tools
    10/27/2020  12:24 PM    <DIR>          zephyr
                   0 File(s)              0 bytes
                  11 Dir(s)  29,099,958,272 bytes free
    
  7. Installing the remaining SDK requirements using pip3:

    pip3 install -r zephyr/scripts/requirements.txt
    

    Note you will get an error during this process related to Visual Studio (not Visual Studio Code). You can ignore this issue.

The ARM Embedded Toolchain

  1. You can download and install the toolchain with this direct link.

  2. One installed, re-open your prompt (or use the provided DOS prompt that will pop up post install) and run arm-none-eabi-gcc --version to make sure it's installed correctly.

    arm-none-eabi-gcc --version
    arm-none-eabi-gcc (GNU Arm Embedded Toolchain 9-2019-q4-major) 9.2.1 20191025 (release)
    Copyright (C) 2019 Free Software Foundation, Inc.
    This is free software; see the source for copying conditions.  There is NO
    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    
  3. You will have to set some important environment variables. Here's what they should look like:

    setx ZEPHYR_TOOLCHAIN_VARIANT gnuarmemb
    setx GNUARMEMB_TOOLCHAIN_PATH "C:\Program Files (x86)\GNU Tools Arm Embedded\9 2019-q4-major"
    

newtmgr (Used to load your application via USB serial bootloader)

  1. For loading code to your nRF9160 Feather, you'll need to download and copy a custom version of newtmgr to a folder in your PATH.

    If you're not sure, C:\bin\ is always a good spot for these types of binaries.

  2. You'll have to make sure that C:\bin\ is added to your system PATH. Hit the start menu or Windows key and type "environment variables". Open the "Edit the system environment variables." option.

  3. Go to the System variables section and find path.

  4. Click Edit Edit system variables

  5. Click New

  6. Enter C:\bin\ into the new line.

  7. Press Ok for the remaining prompts.

  8. Then, you'll need to add your serial profile to make it easier to download/update your device:

    newtmgr conn add serial type=serial connstring="dev=COM5,baud=1000000"
    

    Make sure that the COM port matches the one attached to the nRF9160 Feather. An easy way to check is to remove and add the device to see which COM port shows up in device manager.

  9. Having trouble? You may need to install the Silabs VCP driver.. Download and install the CP210x VCP Windows option.

For more info in using newtmgr checkout the programming section of this documentation.

Testing it

You can quickly test if your SDK is set up correctly by checking out the samples. Make sure that you've closed and re-opened all terminals and Visual Studio Code so the environment is correct. Otherwise you may have issues compiling or flashing code.