Skip to content

Functional Description

Co-Processor/Modem

The "co-processor" or "modem" firmware is provided by Nordic Semiconductor, and is responsible for the hardware network functionality on the nRF9160. The co-processor generally operates independently of the primary ARM core, and is communicated with using Nordic's proprietary communication protocol provided in their linkable BSD library.

Management of the co-processor is done in NimbeLink's "stack" firmware.

Boot Loader

NimbeLink's boot loader is the first image to run when a Skywire Nano first boots. The boot loader is responsible for ensuring a valid stack firmware image is available and has not been tampered with. The boot loader will also perform validation of the application firmware image, whose results will be passed to the stack. The stack will then use those results to decide if it should launch the application firmware image.

Stack

The stack is the primary firmware image running on a Skywire Nano device. The stack will typically run its tasks in the background while the application is running in the foreground. The stack will perform various system tasks, such as running an LWM2M instance, providing logging output to UART0, managing network connections, providing Device Firmware Update (DFU) processes and validation, and forwarding any application requests to the co-processor.

Secure Services

The stack provides a series of callable functions in what is known as "Non-Secure Callable" (NSC) flash and RAM. These are regions of flash and RAM that contain Secure Gateway and branch instructions meant to transfer control from Non-Secure firmware to Secure firmware. The stack will provide Secure Services to applications running on a Skywire Nano using these NSC APIs.

The NimbeLink SDK provides a library for facilitating Secure Service call handling, and most nRF SDK libraries that must run operations through the stack have "offloaded" versions provided by the NimbeLink SDK to automatically use the Secure Service APIs.

For example, the nRF SDK "at_cmd" library will use Secure Services to forward AT commands run by the application to the stack.

The stack will use the Event Generation Unit 2 (EGU2) peripheral on the nRF9160 to send signals to an application indicating that responses or asynchronous messages are available.

Non-Secure                              |   Secure
------------------------------------------------------------------------

Invoke NSC API                          ->  Schedule API handling
                                        <-
Wait for EGU2 interrupt
.                                           Process API call
.                                           Set EGU2 interrupt
Receive EGU2 interrupt
Query pended message with NSC API       ->  Write message to function parameters
                                        <-
Handle response

Some Secure Service calls will be handled immediately during the Non-Secure Callable API invocation, but most will be offloaded to a stack thread for handling. Once a request has been handled, a response will be formed and a signal will be sent to the application that it's ready. The library provided by the NimbeLink SDK will use kernel resources to efficiently suspend the application's calling context while waiting for a response.

AT Commands

AT commands run by the application are first sent to the stack using the Secure Services APIs. AT commands that are intended for the co-processor -- e.g. AT%XHWVERSION -- will be forwarded by the stack to the co-processor. The response will then be sent back to the application.

Some AT commands that are impacted by carrier certification requirements -- e.g. AT+CFUN -- might be intercepted and acted upon by the stack without being forwarded, depending on the current state of the device.

Additional NimbeLink-defined AT commands -- e.g. AT#APPVER -- will be handled entirely by the stack.

NimbeLink recommends using the nRF SDK at_cmd library for running all AT commands from applications.

AT URCs will also be sent asynchronously by the stack to the application. NimbeLink recommends using the nRF SDK at_notif library for handling all AT URCs in applications.

Sockets

Socket operations run by the application -- e.g. socket(), send(), recv() -- are first sent to the stack using the Secure Services APIs. Operations will then be sent to the co-processor by the stack. Responses and results are then sent back to the application. The stack typically does not play a role in managing socket operations, other than providing some resource management for the Non-Secure firmware image.

Logging

The stack will log kernel activity to UART0, which it has permanent Secure control over. There are no verbosity settings currently for logging output, but the logging UART port can be disabled -- thus saving some power consumption cost -- using the stack's AT#UART command.

LWM2M

The stack implements an LWM2M management module, which is used by carriers to faciliate co-processor firmware updates. LWM2M is off by default in stack firmware starting in version v1.2.0. When enabled, LWM2M will automatically handle registration with the network upon boot, and it registers with the appropriate carrier LWM2M network. Part of the operation of the LWM2M library is to:

  1. Connect to the network

  2. Immediately disconnect and reconnect

  3. After about 2.5 minutes, disconnect from and reconnect to the network once again

    At this point, an "LTE ready" URC will be shown to indicate the LWM2M will make no further attempts to change the network registration state

  4. After about 8 minutes - and then again at 15 and 30 minutes - attempt to become "registered" on the LWM2M network

URCs for these events can be used to determine why network registration events are occurring. If the LWM2M module does not become "registered", it will become "deferred".

Device Firmware Update (DFU)

Updates of the co-processor/modem firmware are generally possible at any time. The exception to this rule is if the LWM2M library is in the process of performing a modem Firmware Over the Air (FOTA) update operation.

Firmware updates of stack and/or application firmware are possible at any time, though there might be other limiting factors, such as network availability in the case of FOTA updates.

The logging port (UART0) can be used for a local DFU path. The transfer will use the XMODEM transfer protocol - either 128- or 1024-byte packet sizes - and the UART's flow control lines to ensure data integrity. The UART will automatically have its flow control setting configured by the stack once the DFU has been started, meaning no additional configuration is needed beforehand. The current baud rate setting will be used, however, so if a higher speed is desired it must be configured prior to starting the DFU process. Configuration of UART0 can be performed using the stack's AT#UART AT command.

Firmware updates can be triggered via AT commands to the stack from application firmware. The AT#XFOTA and AT#FWUPD commands can be used by an application to trigger either over-the-air or XMODEM-based updates, respectively.

Firmware updates can also be triggered via an attached debugger using the nRF9160 "mailbox" registers. FOTA updates cannot be triggered from a debugger currently. See the NimbeLink SDK west commands for more information on using debuggers to trigger local updates.