sercp

Sercp [stands for Serial copy] is widely used software for ZX Spectrum and PC intended to send/receive files of any kind between computers. On ZX side Sercp is designed to work as external command of esxDOS. It uses built-in serial port of Spectrum +128K, +2, +2A, +3 connected to internal sound chip’s I/O pins. Now sercp can also be used with eLeMeNt ZX computers, MB03+ interface or SIF Interface. Main motivation for this project was a need to share files between PC and ZX and sometimes between two ZXs using just standard built-in stock hardware.

News 2024 – sercp v0.8

• the ability to communicate at 115200Bd, all on an unmodified Speccy 128. See below
• there is one .sercp version for all supported types of communication interfaces: AY/EL/MB03+/SIF. All interface types allow communication at 38400Bd or turbo at 115200Bd
• to simplify the .sercp syntax, a configuration file with default communication interface and baud rate settings can be used
• the possibility of using a shortened version of the switches (for example -etr instead of -e -t -r)
• unified version numbers for Speccy’s and PC side
• .sercp now uses data block acknowledgment instead of hw flow control
• only RxD and TxD wires are used, no HW flow control issues on some types of usb/serial converters
• pc side of sercp allows communication with older versions of .sercp versions with old „protocol“ and RTS/CTS flow control. See below
• serial cables for ZX Spectrum 128/+2/+2A/+3 are still available – send me e-mail

Main features

• .sercp is included in esxDOS since version 0.8.7
• fastest and most convenient way to send/receive any files to/from Speccy without additional communication hardware
• works well with USB-serial cables as well as standard COM ports (RS-232 standard)
• no need to frequently eject/insert card or disk no more carrying physical media from PC to ZX and vice versa
• transfer is also possible between two Speccys – no need to use PC
• Serial settings: 38400/115200Bd, 8N1, no hw flow control^*
• tested with USB-Serial converters on PC side with following chips: FTDI, PL2303, CP2102 and CH340
• file date/time transfer support^**

*) flow control is not used. Blocks are confirmed by ACK messages – see the technical details
**) .sercp is ready to date/time handling. It requires utime() syscall, since esxDOS v0.8.7

Limitations

• no re-initiate transfer of bad blocks
• uses Speccy’s RAM from 0xC000 to 0xFFFF – see technical information
• works well with files up to 300kB @38400Bd, larger files copy takes too long or use 115200Bd
• max. size of file is 4MiB
• AY’s 115200Bd routines cannot be interrupted by pressing the BREAK key, if there is no response you can send dummy bytes to finish current transfer with an error or press reset
• no LFN support^*
• config file size is limited to 1109 bytes – parsing use fileinfo buffer

*) support will be added after esxDOS gets this feature

Download

*) sercp.exe for 32bit Windows will no longer be provided in the future, if you need it, build it from source

Public read-only git repository is on https://vym.cz/cgit/sercp-pc

Installation

esxDOS: copy (by the traditional way*) sercp to /bin folder and use as common external command by .sercp

.sercp -h            ....is good starting point

PC: copy sercp.exe to path where system finds command. On Linux suggested location is /usr/local/bin. On Windows there is no good place – you can copy sercp.exe to c:\Windows\system\ or similar suitable. Sorry I’m not Windows user.

sercp -h            ....is good starting point

*) traditional way for copying takes many steps: turn off the spectrum, remove CF/SD card, connect card to PC, (auto)mount filesystem, find target folder, find source folder, copy file, unmout card, remove card from pc, connect card to ZX, turn on the Spectrum…

To simplify the .sercp syntax, you can use the configuration file /sys/config/sercp.cfg on the Spectrum. Check out the details.

Compiling from sources

make - compile sources to linux executable file
make install - install sercp  to /usr/local/bin
make sercp.w64 - compile windows exe file - uses mingw
make sercp.w32 - compile windows exe file - uses mingw

On Linux add user to group „dialout“ – no need to run sercp as root (or sudo).

sudo usermod dialout -a -G "user"

On some Linux systems, it may be useful to remove modemmanager or other daemons that use serial ports.

sudo apt-get remove modemmanager or similar dnf remove ...

Using sercp

Send file from Spectrum

.sercp filename.ext
.sercp /path/to/filename.ext

Receive file to Spectrum with optional path to file

.sercp -r
.sercp -r /path/into

Send file from PC

  ---Linux---
sercp -d /dev/ttyUSB0 filename.ext
sercp -d /dev/ttyUSB0 /path/to/filename.ext
  ---Windows---
sercp.exe -d com5 filename.ext
sercp.exe -d com5 \path\to\filename.ext

Receive file to PC to actual folder/directory

  ---Linux---
sercp -d /dev/ttyUSB0 -r
  ---Windows---
sercp.exe -d com5 -r

Configuration file

If a configuration file /sys/config/sercp.cfg exists, .sercp will use the communication interface and baudrate settings from it. Download the file and (un)comment relevant lines for your configuration.

# .sercp configuration file 

# communication interface
interface=AY
#interface=EL
#interface=SIF

# communication speed
baudrate=38400
#baudrate=115200

#  https://vym.cz/sercp
# default interface is AY
# AY  -a serial port on ZXS 128k
# EL  -e USB eLeMeNt ZX / MB03+
# SIF -s SIF UART 16C650

# -t turbo speed 115200Bd
# -n normal speed 38400Bd

You can use .sercp on Your computer without switches. Sercp prints the current interface and baud rate settings in its header.

sercp file.ext          for send file
sercp -r                for receive file      

You can download the configuration file with the following command modified with switches for interface and baud rate:

sercp -r/sys/config/ 

The parameters interface and baudrate are loaded immediately after start .sercp. Importantly, both parameters can be overrided on the command line using the -a -e -s or -t -n switches.

Serial cables

Following schematics show cable connection between ZX and PC. Null modem cable allows to connect two ZXs.

The connector used at Speccy’s serial port is 6-way telephone jack BT631A. ZX Spectrum +128K issue 9G has DB9M connector like ZX Interface 1.

On PC side DB-9F is used to enable easy connection to PC’s serial port / USB-serial converter.

*) ZX Null modem cable for connecting two ZX Spectrums 128. Main difference between standard NULL modem cable and ZX NULL modem cable are connectors DB9M and incomplette wiring. Schema show the solution which is sufficient for serial transfer on ZX.

Standard null modem cable is not usable for ZX<->PC transfer, because it has two DB9F connectors. It is usable for sercp copying files between two PC’s though.

---

Technical information about sercp on Speccy

• Transfer is realized on block basis. Each transfer adds a structure called fileinfo which contains filename, length and checksum of each block
• since .sercp 0.8, ACK messages are used to acknowledge receipt of data blocks
• from version .sercp 0.8 you can use the -t switch to use communication routines at 115200Bd on Speccy’s standard AY serial port
• Hardware flow control is used between blocks not between bytes – this is true for .sercp 0.5 and older
• Block size is 16kiB. Last block may be shorter
• Checksums of blocks is realized as XOR of all bytes and 8-bit SUM of all bytes (both together) – see fileinfo
• Filename format is 8.3 DOS format, no LFN for esxDOS v0.8.x
• .sercp uses Speccy’s RAM from 0xC000 to 0xFFFF as 16kiB buffer for blocks
• The stack is saved into esxDOS’s RAM and once the transfer is finished the stack is recreated to its original place. No need to move RAMTOP

Technical information about sercp on PC

• converts long file names to 8.3 format – first 4 character plus last 8 characters (last 4 characters of name and 4 for suffix „.ext“). Example: longfilename.ext -> longname.ext
• works in command line
• default communication speed is 38400Bd
• switch -t is synonymous with -b115200 to make the setting the same as on the Spectrum
• sercp(.exe) does not require any additional libraries or dependencies
• tested on Linux and Windows
• waits until Speccy saves the block to the storage and sends an ACK confirmation message. Then the transfer continues because Speccy is ready to receive the next block
• source code and windows exe is available – see download section

Refinement of sercp settings for eLeMeNt ZX / MB03+

• Used internal FTDI USB Serial converter
• Serial settings: 38400Bd/115200Bd, 8N1, none
  • use .sercp -e for using element’s internal serial port
  • use -t switch for baudrate 115200
• to install on eLeMeNt ZX you have to replace old /bin/sercp by the new sercp

PC side:

• sercp-pc-0.8 or above is required
• use -t or –turbo to change baudrate
• on some SD cards, especially on a filesystem already loaded with gigabytes of data, writing 16kiB blocks takes a long time. Don’t worry, transfer will continue after successful acknowlidgment

Example:
PC: sercp.exe -d com6 -t file.tap
EL: .sercp -etr

Refinement of sercp settings for SIF Interface

The SIF (Serial InterFace) uses a 16C550 UART chip. Using .sercp with SIF is the same as usual, but you must use the -s switch .

Refinement of sercp for older .sercp on Speccy

Sercp on PC can also be used for communication with older version of .sercp on Spectrum, i.e. using hw flow control. The -l or –hwflow option switches sercp to RTC/CTS flow control mode. No ACK confirmation messages will be sent or required. There is possibility to use switch -o or –oldprot for use old „protocol“ without ACK messages. The difference between -l and -o is that -o does not use hw flow control. This is useful for eLeMent ZX or MB03+ which do not have RTS/CTS wires.

use -l or –hwflow switch to enable RTS/CTS flow control
use -o or –oldprot switch to use old „protocol“ without RTS/CTS flow control

sercp -d /dev/ttyUSB0 -l -w2000 file.ext

You can use switch -w to specify waiting time. For example -w 2000 or more will delay writing of blocks to the SD card. Time is specified in milliseconds. This delay can help with transmission, if the RTC/CTS signaling on the USB/Serial converter is not working properly.

---

fileinfo – internal structure

Fileinfo structure is sent/received before actual file data. Fileinfo size is 1109 bytes. Fileinfo can hold information relevant for up to 256 blocks. Max. file length is 256 x 16kiB = 4MiB. Four megabytes ought to be enough for anyone…

typedef struct {
	uint16_t block_len;	// legth of block
	uint8_t  block_xor;	// xor of all bytes in block
	uint8_t  block_sum;	// 8-bit sum of all bytes in block
} __attribute__((packed)) fi_sum;// used as fi_blocks in fileinfo

typedef struct {
	uint16_t length;	// length of data in fileinfo
	uint8_t h_xor;		// xor of all bytes of fileinfo
	uint8_t h_sum;		// sum of all bytes of fileinfo
	uint8_t fi_numblocks;	// number of transfered blocks
	uint8_t fi_name[64];	// filename (8.3 format for now)
	uint8_t fi_reserved[12];// reserved
	uint16_t fi_time[1];	// fat file time
	uint16_t fi_date[1];	// fat file date
	fi_sum fi_blocks[256];	// blocks - see fi_sums above
} __attribute__((packed)) FILEINFO;

Development

Bug reports and patches are welcome by email.
Public git repository: https://vym.cz/cgit/sercp-pc

---

How was sercp born

Sercp is based on the fast serial transfer routines (written by me ;]). Word „fast“ means really fast relatively to using AY-3-8912’s I/O ports. There are some projects using higher speed than 38.4kBd. For example very nice ROM modification RS-232 ROM from Paul Farrow that works at 57600Bd. But it uses hardware flow control for each byte, overall speed is lower than routines in sercp.

Some „benchmarks“ which I’ve done, show that the baud rate isn’t basic precondition for „fast“ transfer. I’m still writing about the ZX Spectrum 128 and its processor Z80 at 3.54MHz… I tried to write routines which send data from speccy at 115200Bd. The duration of one bit takes 31 tacts (T) of Z80. It works, but preparing bits to send takes more time between bytes and resulting overall speed of transfer is low. Many other serial routines written for speccy and AY suffer from this problem. Receiving at 115200Bd is unrealizable in my opinion … How wrong I was…

This statement was refuted by the ingenious z80 programmers Baze and Zilog, who wrote a routine to receive serial data at 115200Bd via RS232 connected to the AY chip in the Spectrum. After some time, they published a routine called „tukabel“ that did not even have an initialization of the AY chip. When I added this initialization, the program started working without error and I was able to make a video in which the images loaded directly into the Spectrum screen. Courtesy of the authors, sercp uses this routine in turbo mode.
The 115200Bd sending routine comes from an author named MartinM1 with minor modifications by Cygnus. I have no documentation of its origin with a similar story. Sercp also uses this routine courtesy of MartinM1.
Thank you and I trust that sercp will continue to be a good helper.

I decided that most effective baud rate will 38400Bd (~91T per bit). The routines for sending and receiving the data looks similar, but there is some time gap between sending (receiving) bits to rotate accumulator, increase pointer to data and tests for Break key and end of data block. Of course every action is done during actual byte time slot. Byte transfer has precise timing based on start bits. All receiving/sending data manipulation are done at the time of transmission each byte, that allows to use only one stop bit and next byte can folow immediatelly. There is no need (and no time ;]) to flow control between every byte. These facts are the reason what sercp works well with USB-serial cables.

Next step was to write code to read/write files from/to disk using „ultimate“ disk operating system for Speccy – esxDOS. Doing this was amazingly easy with esxDOS services. Many thanks to Miguel Guerreiro for providing esxDOS programmers documentation.

Scope pictures

Some multimedia data

Resources

esxDOS – Papaya Design http://esxdos.org

RS232 ROM by Paul Farrow http://www.fruitcake.plus.com/Sinclair/Interface2/Cartridges/Interface2_RC_New_RS232.htm

Many thanks and greetings to:

• Dušky UB880D for code review, esxDOS support, configuration file parser and tests on SIF and MB03+
• Icons for text revision, testing and moral support
• Baze, Zilog – phenomenal TuKabel reception routine
• MartinM1, Cygnus – sending routine for 115200Bd
• Cygnus, Otis, Lanex, Mikezt and others for testing
• Miguel Guerreiro for his work on esxDOS
• Jan Kučera LMN128 for eLeMeNt ZX and HW and SW support
• and you for using .sercp