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‘s video player.

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. Wozamp requires 115.200bps.