SolarOS

Retro networking · Tutorial

Use a DevKitC-1 as a PPP or SLIP retro modem

Give a computer with an RS-232 port an IPv4 connection through Wi-Fi. An ESP32-S3-DevKitC-1 runs SolarOS, a level converter connects its UART to the computer, and a background job forwards the computer's network traffic through the DevKit's selected Internet connection.

Retro computer          RS-232 adapter       DevKitC-1          Network
PPP or SLIP client <--> RS-232 / 3.3 V <--> SolarOS + NAT <--> Wi-Fi

This setup provides a direct serial network connection. Select a direct or null-modem connection in the computer's networking software and disable modem initialization and dialing scripts: the pppd and slip jobs do not implement Hayes AT commands or a telephone dial tone.

What you need

The quick start covers installation. Open the DevKit's USB-to-UART console at 115200 baud. Keep it connected throughout setup; the retro computer will use a separate UART on GPIO17/18.

Wire the RS-232 converter

Disconnect power before wiring. ESP32 GPIOs use 3.3 V logic; RS-232 signals must pass through the level converter. The MAX3232 data sheet describes its logic inputs/outputs, RS-232 inputs/outputs, and 3 V to 5.5 V supply range. Power this module from 3V3 so its logic output is compatible with the ESP32.

DevKit connectionConverter connectionDirection
3V3VCCPower
GNDGNDCommon reference
GPIO17Logic transmit input, T1IN / DINESP32 to RS-232
GPIO18Logic receive output, R1OUT / ROUTRS-232 to ESP32

Module labels such as TX and RX can describe either the module or its peer. Use the module's schematic to identify the input and output. On its RS-232 side, connect the computer's transmit output to the converter's R1IN, and the converter's T1OUT to the computer's receive input, plus signal ground. For a PC-style DTE DB9 port, those computer signals are pin 3 TX, pin 2 RX, and pin 5 ground. Other connectors need their own pinout.

A module wired as DCE normally uses a straight-through cable to a DTE computer; two DTE connectors need a null-modem crossover. Connector gender alone does not identify its wiring. Never connect an RS-232 signal directly to a GPIO.

This example uses TX, RX, and ground, with 8 data bits, no parity, one stop bit, and no hardware or software flow control. Disable RTS/CTS, DTR/DSR, carrier detection, and XON/XOFF in the client's direct-connection settings.

Bring up Wi-Fi and the dedicated serial port

Run these commands in the DevKit's SolarOS console:

wifi connect "YOUR_SSID" "YOUR_PASSWORD"
wifi status
network status
expansion bus create uart retro port=uart1 tx=17 rx=18 baud=38400
uart mode retro raw
uart status retro
port status retro

Each command occupies one line. retro is the new port name; uart1 is its hardware controller. GPIO17/18 are available expansion pins on this target. The board's uart0, on GPIO43/44, stays available for the management console. Wi-Fi must have an address and be the selected working uplink before testing Internet access from the retro computer.

Start at 38400 baud on both ends. Before enabling a network protocol, open a serial terminal on the retro computer with the same settings and run com retro on SolarOS. Text typed at either terminal should reach the other. Exit COM with the app-exit key (Ctrl+] from a port shell), then close the retro terminal so its networking client can open the serial port.

Only one consumer can own retro. Run either PPP or SLIP below, and stop it before switching protocols or returning to COM.

Option 1: PPP

PPP negotiates the two endpoint addresses and can supply a DNS server. Start the SolarOS side first:

job start pppd retro role=downstream mode=passive local=192.168.8.1 peer=192.168.8.2 dns=auto
job status pppd

downstream enables address translation for the attached computer. passive waits for its client to initiate negotiation. These settings are independent: the routing role controls where traffic goes, while the mode controls who starts PPP. The UART keeps the 38400 baud rate set above.

Configure the computer's PPP client as follows:

Client settingValue
ConnectionDirect serial / null modem, 38400 baud, 8N1
Modem initialization and dial stringDisabled
AuthenticationNo PAP/CHAP requirement; SolarOS PPP is unauthenticated
Computer IPv4 addressNegotiate; SolarOS offers 192.168.8.2
Peer / gateway192.168.8.1
Default routeThrough this PPP connection
DNSRequest from peer, or set a reachable resolver explicitly

dns=auto copies DNS from the current SolarOS uplink when the job starts. If the client cannot negotiate DNS, enter that resolver in its TCP/IP settings. Restart the job after changing the uplink's DNS configuration.

For an optional Linux bench test, attach a USB-to-RS-232 adapter to the same cable. Replace /dev/ttyUSB0 with that adapter's actual device. With the ppp package installed, run on Linux:

sudo pppd /dev/ttyUSB0 38400 local noauth nocrtscts nodetach \
  noipv6 noccp novj 192.168.8.2:192.168.8.1 usepeerdns

This deliberately leaves Linux's existing default route in place. In another Linux terminal, inspect the new interface and test the serial peer:

ip -4 address show ppp0
ping -c 3 192.168.8.1

Use the actual interface name if Linux already has another PPP connection. The pppd manual documents these options. usepeerdns requests DNS; Linux resolver integration depends on the distribution. For an Internet test through this interface, add a route for your chosen test server through ppp0, or configure the PPP connection as the default route when it is your intended uplink.

On SolarOS, job status pppd should report a connected interface, addresses, and NAPT. network status shows the downstream ppp-retro interface.

Option 2: SLIP

Stop the computer's PPP client first, and stop PPP on SolarOS:

job stop pppd
job start slip retro 38400 192.168.7.1 192.168.7.2 255.255.255.252
job status slip

SLIP has no address or DNS negotiation. Set these values in the computer's plain SLIP client; disable CSLIP / Van Jacobson header compression:

Client settingValue
Serial connectionDirect, 38400 baud, 8N1, no flow control
Computer IPv4 address192.168.7.2
Peer / gateway192.168.7.1
Netmask255.255.255.252
Default routeVia 192.168.7.1
DNSA reachable DNS server from your network configuration

SolarOS translates the client's outgoing packets to its selected uplink. network status shows slip-retro. The retro runtime UART keeps its own configured baud rate; change it with uart baud retro RATE while unclaimed if you need a different speed, then match the client and job arguments.

For an optional Linux test, install net-tools and ensure the kernel's slip module is available. Run in one Linux terminal:

sudo modprobe slip
sudo slattach -L -p slip -s 38400 /dev/ttyUSB0

Leave it running. In another terminal, identify the newly created interface with ip link and configure it; this example assumes sl0:

sudo ip address add 192.168.7.2 peer 192.168.7.1 dev sl0
sudo ip link set sl0 up
ping -c 3 192.168.7.1

The explicit -p slip matters because slattach defaults to compressed SLIP. As with the Linux PPP test, configure routing and DNS separately if you want Linux's Internet traffic to use this connection.

Check the connection and stop it

Test in order: reach the SolarOS serial-side address, reach a known external IPv4 address, then resolve a hostname. If only the last test fails, inspect the client's DNS settings. If the serial peer works but external addresses fail, check the client's route and SolarOS wifi status / network status. PPP negotiation timeouts usually point to cabling, baud, flow control, or a client still trying to send modem commands. Garbled text in the earlier COM test must be resolved before troubleshooting IP.

Stop the active protocol on the computer, then on SolarOS use job stop pppd or job stop slip. Confirm port status retro reports it unclaimed. To remove the runtime port entirely:

expansion bus remove retro

The runtime bus and running job do not survive reboot automatically. Once manual setup works, recreate the bus before starting your chosen job in the startup script selected by setterm startup. See the job reference for PPP routing roles and the SLIP reference for the gateway settings.