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.