Cellular

The Toit firmware comes with built-in support for Cellular LTE-M/NB-IoT modems. They offer connectivity speeds from 26 kbit/s up to 4 Mbit/s, depending on modem and network of choice. LTE-M/NB-IoT also offers great coverage and penetration, thus making it ideal for many IoT solutions.

Due to the way connectivity is designed in Toit, setting up Cellular requires two simple steps: configuring the hardware and configuring the connectivity options.

  • Configuring the hardware is done by installing the Toit firmware with some model arguments.

  • Configuring the connection can be done either when installing the Toit firmware or later in the Toit Console.

Modems and Drivers

Currently supported modems are listed here.

ModemAvailable sinceArgument
Ublox Sara R4v1.0.0-p model.cellular.sara.r4=1
Ublox Sara R5v1.1.0-p model.cellular.sara.r5=1
Quectel BG96v1.2.0-p model.cellular.bg96=1
Sequans Monarchv1.2.0-p model.cellular.monarch=1

The following Toit CLI command shows the cellular connection configuration parameters in the serial reinstall command. In this example, the Ublox Sara R4 modem is used:

toit serial reinstall \
  -p model.cellular.enabled=1 \
  -p model.cellular.sara.r4=1 \
  ...

(These model arguments are not yet supported in the Toit console, when flashing directly from the browser. You must use the command line tools for now.)

PWR and RESET

When connecting power, most Cellular modems will not automatically boot. To boot the modem, the PWR pin of the modem must be triggered. Likewise, if something goes wrong, a RESET pin can be used to trigger a Cellular modem reset.

The Firmware knows how to use these pins, but which pin to use is fully optional and thus needs to be configured:

toit serial reinstall \
  -p model.cellular.enabled=1 \
  -p model.cellular.pwr=17 \
  -p model.cellular.reset=16 \
  ...

The PWR pin is mandatory while the RESET pin is optional.

Some Cellular modules use alternative names for the PWR pin, such as WAKE and POWER_ON.

UART

Cellular modems are connected using UART. UART is a bi-directional stream with optional flow control. The base pins are called TX and RX, for Transmitting and Receiving, respectively. Both the microcontroller and the Cellular modem have such pins, and must be connected as TX to RX and RX to TX, such that data transmitted from one will be received by the other.

Cellular UART TX/RX
Cellular UART TX/RX

Some Cellular modules show TX and RX as they should be connected directly by the microcontroller. If connection doesn't work, try swapping RX and TX.

Flow Control

UART also offers flow control, that will help Cellular modems to halt communication when the receiver is busy. They are called RTS and CTS, and unlike TX and RX, they are not cross connected. They work by pulling down RTS when the Cellular Modem can write, and likewise pulling down CTS when the microcontroller can write.

UART with Flow Control

This example shows how do a full setup for PWR and RESET lines (including flow control).

Cellular UART setup with RTS/CTS flow control
Cellular UART setup with RTS/CTS flow control

To configure the Toit firmware (to be installed on your hardware) as shown here, use the following parameters:

toit serial reinstall \
  -p model.cellular.enabled=1 \
  -p model.cellular.rx=23 \
  -p model.cellular.tx=22 \
  -p model.cellular.rts=19 \
  -p model.cellular.cts=18 \
  -p model.cellular.pwr=17 \
  -p model.cellular.reset=16 \
  ...

The selected pins are purely an example, select the GPIO pins that fit your design.

UART without Flow Control

Most Cellular modems and microcontrollers can handle the throughput of the UART, and flow control can be skipped for some designs. To disable flow control, pull RTS low on the Cellular modem and leave CTS unconnected.

This example shows how do a setup without flow control, with PWR and RESET lines.

Cellular UART setup without flow control
Cellular UART setup without flow control

For the command, simply omit RTS and CTS:

toit serial reinstall \
  -p model.cellular.enabled=1 \
  -p model.cellular.rx=23 \
  -p model.cellular.tx=22 \
  -p model.cellular.pwr=17 \
  -p model.cellular.reset=16 \
  ...

Configure Cellular Connection

While cellular always requires at least one setting, the APN, there are a few more for use in different regions around the world.

NameArgumentDescription
APN-p cellular.apn=onomondoThe virtual network name that modem should connect to. This is provided by the Sim Card issuer, and is e.g. onomondo for Onomondo and soracom.io for Soracom.
Bands-p cellular.bands=2,5,20List of bands to search for. These are dependent on the region, e.g. EU, NA and Asia
Operator-p cellular.operator=23801By default, the modem will search and connect to the best suited operator. However, this can be overridden and pinned to a single one, by using this command.

Examples

Pycom GPy

Toit can run on the Pycom GPy, with support for the Sequans Monarch cellular modem embedded into it. As the GPy is fully embedded, the pin configuration is already pre-determined.

NamePin
TX5
RX23
RTS19
CTS18
WAKE27

The GPy can thus easily be enabled to run with a cellular stack. The following command shows how to install the Toit firmware configured to use the cellular stack with an Onomondo Sim Card.

toit serial reinstall \
  -p model.cellular.enabled=1 \
  -p model.cellular.tx=5 \
  -p model.cellular.rx=23 \
  -p model.cellular.rts=19 \
  -p model.cellular.cts=18 \
  -p model.cellular.pwr=27 \
  -p model.cellular.monarch=1 \
  -p cellular.apn=onomondo \
  --port=/dev/ttyACM0