Nordic SoC

VS Code is the only IDE that has extensions for Nordic Connect, so you will want to use that and download the Nordic Connect extensions.

Installing nrfutil

Download nrfutil, make it executable and move it somewhere where the path can pick it up, e.g.: ~/.local/bin/. You will also need to install the device module with it:

nrfutil search
nrfutil install device

Installing the SDK

I recommend installing version 3.0.2 because it just works whereas 3.1.0 runs into many issues.

3.0.2

Follow the walkthrough for VS Code: vscode:/nordic-semiconductor.nrf-connect-extension-pack/quickstart and select 3.0.2.

3.1.0

Note: I could not get my project to build with this version.

It's easiest to follow the walkthrough for VS Code: vscode:/nordic-semiconductor.nrf-connect-extension-pack/quickstart. I had an issue where installing the SDK would fail, checking the logs it threw on unpacking the SDK archive. I attempting to manually extract this and found that it failed beacause it contained some ridiculously long filenames in there, specifically:

v3.1.0/modules/lib/matter/examples/chef/devices/rootnode_contactsensor_lightsensor_occupancysensor_temperaturesensor_pressuresensor_flowsensor_humiditysensor_airqualitysensor_powersource_367e7cea91

That wasn't the only long file, so I extracted everything but v3.1.0/modules/lib/matter/examples/chef/devices and then extracted file that wasn't too long in that. You will want it extracted to ~/ncs/v3.1.0 but you want to rename it to something else temporarily - click install in VS Code, select the SDK/Version and when it asks for the install path don't hit enter just yet, first rename the directory back to v3.1.0 then hit enter in VS Code and it will detect that it is already installed and work fine. If you don't rename it first VS Code will complain that the directory already exists and if you don't have it named in the right place VS Code will attempt to install it normally and fail again.

Networking

Docs: https://docs.nordicsemi.com/bundle/ref_at_commands_nrf91x1/page/REF/at_commands/intro_nrf91x1.html

Enable Serial AT Commands

CONFIG_AT_HOST_LIBRARY=y
CONFIG_UART_INTERRUPT_DRIVEN=y

Modem Init

// CONFIG_NRF_MODEM_LIB=y
#include <modem/nrf_modem_lib.h>

// Init modem manually (auto init is disabled)
int err = nrf_modem_lib_init();

if (err < 0) {
  printk("Modem init failed: %d\n", err);
}

RAT Selection

Radio Access Technology (RAT). You can enable LTE-M, NB-IoT and GNSS or a combination of these RATs. If you have more than one selected you can configure what one is prefered.

Option 1, force by config.

CONFIG_LTE_NETWORK_MODE_NBIOT=y

Option 2, use lte link control.

// CONFIG_LTE_LINK_CONTROL=y ?
#include <modem/lte_lc.h>

int err = lte_lc_system_mode_set(LTE_LC_SYSTEM_MODE_NBIOT, LTE_LC_SYSTEM_MODE_PREFER_NBIOT);

if (!err) {
  printk("RAT Set: %d\n", err);
} else {
  printk("Failed to set RAT: %d\n", err);
}

Option 3, use AT commands:

#include <nrf_modem_at.h>
char resp[64];

// AT%XSYSTEMMODE=<LTE-M 1/0>,<NB-IoT 1/0>,<GNSS 1/0>,<Preference 0=none,1=LTE-M,2=NB-IoT,3=SIM-preference-or-LTE-M,4=SIM-preference-or-NB-IoT>
int err = nrf_modem_at_cmd(resp, sizeof(resp), "AT%%XSYSTEMMODE=0,1,0,2");
if (!err) {
  printk("Set system mode: %s\n", resp);
} else {
  printk("Failed to set system mode: %d\n", err);
}

Public Land Mobile Network (PLMN)

The PLMN is a combination of Mobile Country Code (MCC) and Mobile Network Code (MNC). MCC is a 3 digit number assigned to the country, MNC is a 2 digit code assigned to the network operator. PLMN is MCC concatenated with MNC.

You can find the MCC and MNC here: https://www.mcc-mnc.com

Reading Current

#include <nrf_modem_at.h>

char resp[64];
int err = nrf_modem_at_cmd(resp, sizeof(resp), "AT+COPS?");
if (!err){
  printk(resp);
  /* E.g.
  +COPS: 0,2,"26201",7
  OK
  */
} else {
  printk("Failed to assign operator: %d\n", err);
}

Manual Selection

This example uses NZ MCC: 530 with One's MNC 01:

#include <nrf_modem_at.h>

const char *PLMN = "53001";
char resp[64];

// AT+COPS=<Mode 0=automatic,1=manual>,<Format=0=Long-Alphanumeric,1=Short-Alphanumeric,2=Numeric>
int err = nrf_modem_at_cmd(resp, sizeof(resp), "AT+COPS=1,2,\"%s\"", PLMN);
if (!err){
  printk("Assigned operator: %s\n", resp);
} else {
  printk("Failed to assign operator: %d\n", err);
}

Manual Band Selection

You can get or set the bitmask for what bands are permitted, this looks like a string of 1s & 0s where the position (reading from the right) of the 1 is the band that is enabled.

You should check the band on NVM and only set it if it's not already set in order to save NVM write cycles and power.

This example selects bands 3 and 28.

#include <nrf_modem_at.h>

const char *BAND_BIT_MASK = "1000000000000000000000000100";
char resp[128];
// AT%XBANDLOCK=<Mode 0=remove-lock,1=persistant-lock,2=runtime-lock>,<Mask>
int err = nrf_modem_at_cmd(resp, sizeof(resp), "AT%%XBANDLOCK=1,\"%s\"", BAND_BIT_MASK);
if (!err) {
  printk("Assigned bit mask: %s\n", resp);
} else {
  printk("Failed to assign bit mask: %d\n", err);
}

Sync

You can do a synchronous request which will hang your code until it connects or throws.

// CONFIG_LTE_LINK_CONTROL=y
#include <modem/lte_lc.h>

int err = lte_lc_connect();

if (err) {
  printk("LTE connect failed: %d\n", err);
}

Async

// CONFIG_LTE_LINK_CONTROL=y
#include <modem/lte_lc.h>

static void lte_handler(const struct lte_lc_evt *const evt) {
  if (evt->type == LTE_LC_EVT_NW_REG_STATUS) {
    switch (evt->nw_reg_status) {
    case LTE_LC_NW_REG_REGISTERED_HOME:
      printk("Registered to home network\n");
      break;
    case LTE_LC_NW_REG_REGISTERED_ROAMING:
      printk("Registered to roaming network\n");
      break;
    case LTE_LC_NW_REG_SEARCHING:
      printk("Searching for network\n");
      break;
    case LTE_LC_NW_REG_REGISTRATION_DENIED:
      printk("Registration denied\n");
      break;
    case LTE_LC_NW_REG_UNKNOWN:
      printk("Network status unknown\n");
      break;
    default:
      printk("Network registration failed or unknown status: %d\n", evt->nw_reg_status);
      break;
    }
  }
}

int err = lte_lc_connect_async(lte_handler);
if (err) {
  printk("start connect failed, err %d\n", err);
} else {
  printk("connect started\n");
}

Get SIM Status

The SIM will return error until it lte_lc_connect gets called.

#include <nrf_modem_at.h>

char resp[128];
int err = nrf_modem_at_cmd(resp, sizeof(resp), "AT+CPIN?");

if (err) {
  printk("Failed to get SIM status, err %d\n", err);
} else {
  printk("SIM status: %s\n", resp);
}

Get Connection Status

< -100 dBm is a poor connection.

// CONFIG_LTE_LC_CONN_EVAL_MODULE=y
#include <modem/lte_lc.h>
#include <include/modem/modem_info.h>

struct lte_lc_conn_eval_params params;
int err = lte_lc_conn_eval_params_get(&params);

if (err == 0) {
  printk("RSRP: %d dBm\n", RSRP_IDX_TO_DBM(params.rsrp));
  printk("SNR: %d dB\n", params.snr);
  printk("Cell ID: %d\n", params.cell_id);
  printk("Band: %d\n", params.band);
} else {
  printk("Connection evaluation failed: %d\n", err);
}

APN/PDP

Access Point Name (APN) is the name of the access point that the device should connect to, it defines the destination network and connection rules. Packet Data Protocol (PDP) is the protocol that sets up a logical connection between the device and that network and provides PDP contexts which is essentially a tunnel over the connection. If you configure the Packet Data Network (PDN) to PDN_FAM_NONIP you are configuring it so that it sends packets of raw data and the network will need to be configured for Non IP Data Delivery (NIDD) and you specify where it should go. Given that it doesn't have the overhead of IP it saves some data but can have higher latency.

you can configure the default APN in the config or there might be one already configured on the sim.

CONFIG_PDN_DEFAULT_APN="apn.iot.example"

// CONFIG_PDN=y
// CONFIG_PDN_DEFAULTS_OVERRIDE=y
#include <modem/pdn.h>
uint8_t cid;
int err;

err = pdn_ctx_create(&cid, NULL);

if (err && err != -EALREADY) {
  printk("Failed to get CID: %d\n", err);
  return err;
}

printk("pdn_ctx_create returned %d, cid: %d\n", ret, cid);

// Can PDN_FAM_IPV4V6, PDN_FAM_IPV4, PDN_FAM_IPV6 or PDN_FAM_NONIP (NIDD)
err = pdn_ctx_configure(cid, "apn.iot.example", PDN_FAM_IPV4V6, NULL);
if (err) {
  printk("Failed to configure APN: %d\n", err);
  return err;
}

Link Connection Power Saving Mode

// CONFIG_LTE_LC_PSM_MODULE=y
#include <modem/lte_lc.h>

/**
 * Request modem to enable or disable Power Saving Mode (PSM).
 *
 * PSM parameters can be set using `CONFIG_LTE_PSM_REQ_FORMAT`,
 * `CONFIG_LTE_PSM_REQ_RPTAU`, `CONFIG_LTE_PSM_REQ_RAT`,
 * `CONFIG_LTE_PSM_REQ_RPTAU_SECONDS` and `CONFIG_LTE_PSM_REQ_RAT_SECONDS`,
 * or by calling lte_lc_psm_param_set() or lte_lc_psm_param_set_seconds().
 *
 * @note `CONFIG_LTE_PSM_REQ` can be set to enable PSM, which is generally sufficient. This
 *       option allows explicit disabling/enabling of PSM requesting after modem initialization.
 *       Calling this function for run-time control is possible, but it should be noted that
 *       conflicts may arise with the value set by `CONFIG_LTE_PSM_REQ` if it is called
 *       during modem initialization.
*/
int err = lte_lc_psm_req(false);
if (err) {
  printk("Failed to disable PSM: %d\n", err);
} else {
  printk("PSM disabled.\n");
}

Get Modem Firmware

char resp[64];
int err = nrf_modem_at_cmd(resp, sizeof(resp), "AT+CGMR");
if (!err) {
  printk("Modem firmware: %s\n", resp);
} else {
  printk("Failed to get modem firmware: %d\n", err);
}

Get Signal Quality

This always returns 99,99 which means error despite having a connect, need to use the connection evaluation in the other example.

char resp[64];
int err = nrf_modem_at_cmd(resp, sizeof(resp), "AT+CSQ");
if (!err) {
  printk("Signal quality: %s\n", resp);
} else {
  printk("Failed to get signal quality: %d\n", err);
}

Get Connection Details

char resp[64];
int err = nrf_modem_at_cmd(resp, sizeof(resp), "AT%%XMONITOR");
if (!err) {
  printk("Connection details: %s\n", resp);
} else {
  printk("Failed to get connection details: %d\n", err);
}

GPIO

GPIO although can be done directly is setup through references in a device tree, you can add your own references to circuits and reference them with with nice references that make sense in the code.

// CONFIG_GPIO=y
#include <zephyr/kernel.h>
#include <zephyr/drivers/gpio.h>

#define SLEEP_TIME_MS 100
#define LED0_NODE DT_ALIAS(led0)

int err;
bool led_state = true;

if (!gpio_is_ready_dt(&led)) {
  printf("error: GPIO is not ready");
  return 0;
}

err = gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);

if (err < 0) {
  printf("could not configure pin");
  return 0;
}

while (1) {
  reterr= gpio_pin_toggle_dt(&led);

  if (err < 0) {
    return 0;
  }

  led_state = !led_state;
  printf("LED state: %s\n", led_state ? "ON" : "OFF");
  k_msleep(SLEEP_TIME_MS);
}