Radio networking · Tutorial
Reach a Linux shell over a LoRa SolarLink
Use two LoRa-capable SolarOS devices to carry a terminal connection to a Linux computer. SolarOS Link turns the radio packets into an ordered byte stream; a bridge on the Linux-side device joins that stream to USB serial.
Keyboard / terminal LoRa packets USB serial Linux
SolarOS A: com vser0 <--> SolarOS B: bridge <--> ttyACM0 <--> serial login
The Linux computer can be outside Wi-Fi coverage. Neither SolarOS device needs an IP network for this connection. This SolarLink uses ordinary SolarOS Link over LoRa; the Waveshare SolarLink expansion card is another hardware option, rather than a required part of this setup.
Choose the devices
The complete wiring example uses two ESP32-S3-DevKitC-1-N16R8 boards, each with an RFM95W LoRa module and the current SolarOS full image for esp32_s3_devkitc1_n16r8. A board with a supported built-in LoRa radio can replace either one: inspect expansion devices and radio list, and use its existing radio ID instead of attaching another radio.
You also need antennas matched to both modules' frequency band, a keyboard and shell for device A, and Linux with agetty from util-linux. For a headless DevKit A, use its USB-to-UART console at 115200 baud. A handheld with a display and keyboard can run the same com vser0 command from its own shell.
Device B needs a native USB CDC port for the Linux data connection and a separate management shell. On this DevKit, use the USB-to-UART connector for B's uart0 console and the native USB connector for Linux's cdc0 connection. A USB-to-UART connector does not provide cdc0. Another board needs an equivalent free duplex port and its own appropriate wiring.
Link streams are unencrypted, and peer IDs can be spoofed. A serial Linux login, including its password and subsequent commands, travels in clear text over this radio path. Use this example on a trusted test link with an ordinary unprivileged Linux account; it does not provide SSH's security.
Attach the radios
Power off both DevKits. On each one, wire the RFM95W as follows:
| RFM95W | DevKitC-1 |
|---|---|
| VCC | 3V3 |
| GND | GND |
| SCK | GPIO12 |
| MOSI | GPIO11 |
| MISO | GPIO13 |
| NSS / CS | GPIO4 |
| RESET | GPIO5 |
Connect the antennas before transmitting. The driver polls the radio, so DIO0 is optional. The RFM95W wiring reference describes this same attachment. In each DevKit's management shell, run:
expansion attach rfm95 radio0 spi=spi0 cs=gpio4 reset=gpio5
radio status radio0
radio profile list
radio profile show lora-eu868
Skip the attach command when using a board-owned radio. Both ends need the same frequency, bandwidth, spreading factor, coding rate, sync word, CRC, and packet framing. The built-in lora-eu868 profile supplies a complete 868 MHz LoRa configuration; use it only with suitable modules and where those settings and your airtime are permitted. For another band, configure and save a suitable complete radio profile on both devices before starting Link.
The profile name does not enforce local transmit-power or airtime limits. Keep initial exchanges brief and account for acknowledgements and retries.
Establish the packet link
Run this on both A and B, using your chosen profile if it differs:
job start radio-link link0 radio0 lora-eu868
link status link0
link send link0 broadcast "hello"
Run link receive link0 1000 on each side to check it received the other device's greeting. Note each device's local ID from link status link0. The following IDs are examples:
| Device | Example local ID | Bind its stream to |
|---|---|---|
| A, operator terminal | 0x7b1fdb02 | B's ID, 0xde63d29e |
| B, Linux bridge | 0xde63d29e | A's ID, 0x7b1fdb02 |
On A, substitute B's actual ID:
link stream create link0 vser0 0xde63d29e
link stream status vser0
On B, substitute A's actual ID:
link stream create link0 vser0 0x7b1fdb02
link stream status vser0
The local port name vser0 is the same for convenience. It is initially closed: a consumer opens it when it claims the port. Both firmwares must support the same Link stream protocol; current firmware uses version 3. This virtual port adds segmentation, ordering, retries, and backpressure.
Bridge B's virtual port to Linux
Keep working from B's separate management console. Inspect the native USB port and its owners:
port list
session list
log sink cdc off
port status cdc0
The DevKit normally boots in native USB device mode. If cdc0 is absent, inspect usb status and use usb mode device from the management shell to enable it after releasing any conflicting USB or pin owners.
If a shell owns cdc0, close that session using its actual numeric ID from session list, for example session close 2. Retain the uart0 management shell. Release any other bridge, logger, or application that owns cdc0. Then run on B:
job start bridge cdc0 vser0
job status bridge
This is the port-to-port bridge form. Both endpoints remain exclusively owned by the bridge until it stops. Use vser0 here: bridging directly to link0 would use the best-effort packet adapter instead of the reliable stream.
Connect B's native USB connector to Linux. Identify the corresponding serial device on Linux, for example:
ls -l /dev/serial/by-id/
Use the native CDC device, not B's separate USB-to-UART console. The following commands assume it is /dev/ttyACM0; substitute the actual device. Close any serial monitor using that device, and check that a serial-getty service or another host application is not already consuming it.
Start a Linux serial login
In a local Linux terminal, start a foreground login on that port:
sudo agetty --local-line=always --8bits --noclear --noissue 115200 ttyACM0 dumb
agetty prompts for an existing Linux username and invokes the normal login program. --local-line=always removes the need for a carrier-detect wire; --8bits selects an eight-bit line. dumb keeps the initial terminal simple. The nominal CDC baud rate does not set the LoRa bitrate. These options are documented in the agetty manual.
Now run on A, from its display shell or USB-to-UART console:
com vser0
Press Enter if the login prompt was sent before A connected. Log in with the ordinary Linux account, then try small commands:
whoami
hostname
pwd
printf 'Hello over LoRa\n'
Those commands run on Linux. B only forwards bytes, and A displays the terminal. com works from a port shell as well as a display shell; its input shell port must differ from its selected vser0 port.
Use short command output initially. LoRa is half duplex, and packet airtime, acknowledgements, and retries make it much slower than the USB connection. Large directory listings, full-screen redraws, and continuous logs can occupy the link for a long time. Stream backpressure bounds buffering; it does not increase radio throughput.
Inspect and close the connection
From a management shell, inspect:
link status link0
link stream status vser0
job status radio-link
On B, also use job status bridge and port status cdc0. A working connection shows stream traffic in both directions. A stream that remains disconnected usually means the peer ID is wrong, the other consumer has not opened its port, or the radio profiles do not match. Growing retry counters point toward a lossy path or airtime contention. Check the greeting exchange before Linux login configuration. Raw stream packets do not appear in link receive.
When finished, run exit in the Linux shell. This logs the Linux user out; simply exiting COM leaves that remote login active. The foreground agetty invocation is a single login rather than a persistent service. Exit COM with the app-exit key (Ctrl+] from a port shell). On B, stop the bridge:
job stop bridge
Then, with all consumers closed, run on both devices:
link stream remove vser0
job stop radio-link
These runtime commands need to be repeated after reboot. If you later add startup configuration, keep the order: attach radio, start radio-link, create the peer-bound stream, then start its consumer. The Link manual covers the stream protocol, counters, and alternative transports such as ESP-NOW.