surl-server is a serial-to-network proxy designed for 8bit computers, and especially for the Apple II series. It is based on libraries like CURL, jq, ffmpeg and more, and provides a way for these old computers to :

• Fetch and send data over the internet, using any protocol CURL supports
• Parse JSON responses
• Convert text from UTF-8 to the native charset and vice-versa
• Convert modern image formats to native graphics representation
• Stream video
• Stream audio

Installing surl-server

The easiest way to install the proxy is to get a pre-built Raspberry image on my github’s Releases page.

Download the latest surl-server-bullseye-YYYY-MM-DD-lite.img.gz.

Uncompress it and copy it to a micro-SD card. You can do it using command-line on most platforms, or use a tool like Balena Etcher to do it interactively. Here is how to do it via command-line (substitute YYYY-MM-DD for the file you downloaded, and /dev/mmcblk0 for your microSD’s device file):

gunzip surl-server-RELEASE-YYYY-MM-DD-lite.img.gz
sudo dd if=surl-server-RELEASE-YYYY-MM-DD-lite.img of=/dev/mmcblk0

You can now insert the microSD card in a Raspberry, plug it into your Ethernet network, and boot it.

By default, the booted OS will present itself on the local network as surl-server.local. You can ssh to it using the default Raspberry login and password: pi/raspberry.

Upgrading surl-server

It is quite often that the programs I develop for my Apple II require modifications to the proxy. It is often new features, but sometimes reworking of existing features; this means that the client program and the proxy have to agree on a protocol to talk to each other. To make sure mismatches don’t happen, a protocol version number is exchanged between the client and the proxy. If you get “surl-server Protocol X required”, this means you either have a too old, or too recent, surl-server. To upgrade it, you can either download a new image from my Releases page, or ssh to the surl-server proxy and issue the following commands:

sudo apt update
sudo apt install --reinstall surl-server

Minimal requirements

The surl-server proxy is relatively lightweight, and will function with a good level of performance on a Raspberry Pi 3. Some features are more CPU intensive, for example video streaming. You would wait a shorter time to watch streamed videos with a Raspberry Pi 4.

Deploying on other hardware

A Rapsberry Pi is not a requirement. surl-server will happily run on a normal computer. No pre-built binaries are provided for this, but you can compile it yourself easily under Linux:

git clone https://github.com/colinleroy/a2tools.git
cd a2tools

#install build dependancies (you can check the uptodate
#list in src/debian/control, Build-Depends section)

sudo apt install libcurl4-gnutls-dev libgumbo-dev \
  libjq-dev libsdl-image1.2-dev libavcodec-dev \
  libavformat-dev libavfilter-dev libavutil-dev \
  libswresample-dev libpng-dev

cd src/surl-server
make clean all install

Serial configuration

The surl-server configuration file is located in /etc/a2tools/tty.conf. If this file is absent, running surl-server will provide you with an example configuration file:

tty: /dev/ttyUSB0
baudrate: 115200
hw_handshake: off
aux_tty: /dev/ttyUSB1

The only parameter you should need to change is the tty: adapt it to the device name of your USB-serial adapter. The aux_tty: parameter is optional and only used by Wozamp, IInvidious and Mastodon video players.

If you want to use the dual-port setup, the hardest part is to make sure the USB-serial adapters are recognized correctly each time. In order to achieve that, the easiest is to have two different models of USB adapters, and configure tty.conf in this way: plug in one USB adapter and do

root@surl-server:~# ls -l /dev/serial/by-id/
total 0
lrwxrwxrwx 1 root root 13 11 avril 03:17 usb-Prolific_Technology_Inc._USB-
Serial_Controller-if00-port0 -> ../../ttyUSB0

Plug the second one and re-do the same command:

root@surl-server:~# ls -l /dev/serial/by-id/
total 0
lrwxrwxrwx 1 root root 13 11 avril 03:17 usb-FTDI_FT232R_USB_UART_AB0PXCGI-
if00-port0 -> ../../ttyUSB1
lrwxrwxrwx 1 root root 13 11 avril 03:17 usb-Prolific_Technology_Inc._USB-
Serial_Controller-if00-port0 -> ../../ttyUSB0

You can now set these paths into tty.conf:

root@surl-server:~# cat /etc/a2tools/tty.conf
tty: /dev/serial/by-id/usb-Prolific_Technology_Inc._USB-
Serial_Controller-if00-port0
baudrate: 115200
hw_handshake: on
aux_tty: /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_AB0PXCGI-if00-port0

If you change the baudrate, the client programs will need reconfiguration too. They will suggest you do so when they fail connecting to the proxy. Audio and audio-video streaming requires 115.200bps. But there is no reason that you would need to change the baudrate.