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.
| Modem | Available since | Argument |
| Ublox Sara R4 | v1.0.0 | -p model.cellular.sara.r4=1 |
| Ublox Sara R5 | v1.1.0 | -p model.cellular.sara.r5=1 |
| Quectel BG96 | v1.2.0 | -p model.cellular.bg96=1 |
| Sequans Monarch | v1.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:
(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.
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).
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.
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.
| Name | Argument | Description |
| APN | -p cellular.apn=onomondo | The 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,20 | List of bands to search for. These are dependent on the region, e.g. EU, NA and Asia |
| Operator | -p cellular.operator=23801 | By 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.
| Name | Pin |
| TX | 5 |
| RX | 23 |
| RTS | 19 |
| CTS | 18 |
| WAKE | 27 |
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.