Tethering

Tethering is a feature in Device OS 6.2.0 that allows another device to communicate with the Internet using a Particle B-Series SoM cellular modem. This can be used from a Raspberry Pi, for example, to allow it to access the Internet through the Particle B-SoM cellular device.

Requirements

LTE Cat 1 cellular module

This features requires a LTE Cat 1 cellular module, available on these SKUs.

You cannot use a LTE Cat M1 module, such as the B404X, Boron 404X, or M404.

Serial connection

Tethering uses a UART serial connection between the other device (such as a Rasbperry Pi) and the Particle device. Hardware flow control (RTS/CTS) is recommended, as is using a high baud rate. 921600 baud works well.

All current Particle devices have 3.3V logic on UART ports, so if your other device is a 5V device, it would need level shifters. Raspberry Pi devices are 3.3V.

PPP support

Over this serial connection PPP (point-to-point protocol) is used. This allows the other device to get an IP address and use features like TCP, UDP, and DNS to transmit data to and from the Internet.

It is not restricted to using the Particle cloud, but it cannot establish permanent listening sockets for TCP or UDP because these are not supported by the cellular networks.

Note that the other device must support PPP, so you cannot use this for devices like Arduino that do not support PPP over UART serial as a network connection.

Data usage

Tethering can use a very large amount of cellular data. Caution should be used with the existing Particle data plans as you can easily exceed your allowed cellular data limit.

Contact sales if you have a need for higher data allowances.

Application firmware

In order to use tethering, it must be enabled:

For information about the Tether class, see the Device OS API reference.

TCP and UDP

It is possible to use TCPServer, TCPClient, and UDP to communicate between the other device and the Particle device over TCP or UDP over the tethering connection.

When binding listening connections, or making an outgoing connection or sending packets, an optional nif specifies the network interface to use. This can be Tether for the tethering interface.

Particle M.2 breakout

If you are using the M.2 breakout board or M.2 evaluation board with the B504 and B524, you will be using these pins on the expansion header.

SoM custom board

If you are using your own custom board you will be using these pins on the B504 and B524 B-Series SoM.

Raspberry Pi

If using a Raspberry Pi as the other device, you must configure it to establish a PPP connection over its serial port instead of Ethernet or Wi-Fi.

• Be sure to cross TX ↔ RX between the Pi and the B-SoM. For example, the Particle TX connects to the Pi RX.
• Be sure the GND pin is connected between the Pi and the B-SoM.
• Do not connect 3V3 or 5V between the Pi and B-SoM!
• You may connect the Pi 5V to Particle device VIN if you are powering the Particle device from the Pi hat connector.

This section is separated into two parts. The first is the easy method using 460 Kbaud without flow control on UART0, which works on both the Pi 4 and Pi 5.

If you are building your own board, you may want to use the second method, which uses 912 Kbaud with hardware flow control (RTS/CTS). See Using flow control, below.

Serial connections - Raspberry Pi

The setup script, below, uses UART0 without flow control for the tethering connection on the Raspberry Pi. It can be used on both the Pi 4 and Pi 5.

Setup script - Raspberry Pi

The script below makes it easy if you are using Debian 12 "bookworm" for 32-bit or 64-bit ARM on a Raspberry Pi 4 or Raspberry Pi 5.

Download and run this script on your Raspberry Pi:

bash enable-tethering.sh

This script:

1. Disables the linux serial console on the USART needed for tethering
2. Enables a USART with flow control on the USART pins
3. Disable sany PPP options, create default options for the new tty PPP device
4. Adds udev rules for the new PPP tty device
5. Scans for the modem in modem manager
6. Creates a connection to the modem using NetworkManager

Using flow control - Raspberry Pi

Using flow control with a 912 Kbaud data rate provides the optimal performance and is recommended if you are designing your own board.

One important caveat: On the Pi 4, UART0 does not support hardware flow control. Thus you need to use separate pins for Pi 4 vs. Pi 5.

Be sure to cross TX ↔ RX and CTS ↔ RTS between the Pi and the B-SoM. For example, the Particle CTS connects to the Pi RTS.

Serial with flow control - Raspberry Pi 5

The setup script, below, uses UART0 for the tethering connection on the Raspberry Pi 5.

If you wish to use a different port, the following ports are available on the Raspberry Pi 5.

Serial with flow control - Raspberry Pi 4

The setup script below uses UART2 on the Raspberry Pi 4 because UART0 does not support hardware flow control on the Pi 4.

If you wish to use a different port, the following ports are available on the Raspberry Pi 4.

Setup script with flow control - Raspberry Pi

The script below makes it easy if you are using Debian 12 "bookworm" for 32-bit or 64-bit ARM on a Raspberry Pi 4 or Raspberry Pi 5.

Download and run this script on your Raspberry Pi:

bash enable-tethering.sh

This script:

1. Disables the linux serial console on the USART needed for tethering
2. Enables a USART with flow control on the USART pins
3. Disable sany PPP options, create default options for the new tty PPP device
4. Adds udev rules for the new PPP tty device
5. Scans for the modem in modem manager
6. Creates a connection to the modem using NetworkManager

Manual setup - Raspberry Pi

If you prefer to set up the connection manually, these notes may be helpful.

Manual Linux setup notes

# /etc/udev/rules.d/78-mm-user.rules 
ACTION!="add|change|move", GOTO="mm_user_rules_end"
DEVPATH=="/sys/devices/platform/soc/fe215040.serial/tty/ttyS0", ENV{ID_MM_PLATFORM_DRIVER_PROBE}="1"
LABEL="mm_user_rules_end"

# /etc/udev/rules.d/78-mm-user1.rules
ACTION=="add|change|move", KERNEL=="ttyS0", ENV{ID_MM_TTY_BAUDRATE}="921600", ENV{ID_MM_CANDIDATE}="1", ENV{ID_MM_PLATFORM_DRIVER_PROBE}="1", ENV{ID_MM_DEVICE_PROCESS}="1"

# /etc/udev/rules.d/78-mm-particle.rules 
ACTION=="add|change|move", KERNEL=="ttyAMA0", ENV{ID_MM_TTY_FLOW_CONTROL}="none", ENV{ID_MM_TTY_BAUDRATE}="921600" ENV{ID_MM_DEVICE_PROCESS}="1"

$ sudo udevadm control -R
$ sudo udevadm trigger
$ sudo mmcli -S # Scan
$ sudo mmcli -L # Retry a few times, give MM some time to detect the "modem"
$ sudo mmcli -m 0 # This should provide detailed info on the detected "modem"

local

$ sudo nmcli connection edit type gsm con-name "particle"
nm > set gsm.apn "particle"
nm > set connection.interface "ttyS0"
nm > set ppp.crtscts true # explicitly enable flow control
nm > save
nm > # answer yes to auto-connect
nm > (Ctrl-D)

$ sudo nmcli connection edit type gsm con-name "particle"
nmcli> set gsm.apn particle
nmcli> set connection.interface ttyAMA0
nmcli> set ppp.crtscts true # explicitly enable flow control
nmcli> save
Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection.
Do you still want to save? (yes/no) [yes] yes
nmcli> (Ctrl-D)

$ nmcli con show particle
connection.id:                          particle
connection.uuid:                        9a95121b-22b7-44b2-9991-f69ac0f7194a
connection.stable-id:                   --
connection.type:                        gsm
connection.interface-name:              ttyS0
connection.autoconnect:                 yes
...