post

My retro toolchain

About my toolchains for retro computing.

Tools are very personal choice, what works for me. I use Windows (11 now) as my main workstation and often the command line. I do have Linux desktops for compatibility testing. As I grew up in the 80ties with mini’s like HP1000, PDP-11 + RSX-11M, VAX/VMS, MS-DOS, all command line, many many editors, from line editors to screen oriented (EDT from DEC was great!) with all kind of automation tools and code management, I feel comfortable with what Windows (and Linux) offer me now, it makes me very productive! YMMV, pick your tools as you like it.

Tools development
When there is not a tool available that does easy what I need, I write my own. GUI or command line, depending on the context.
My toolchain consists of Freepascal (commandline) and Lazarus (GUI).
Most tools have to do with manipulating binary data as to be expected. Other areas are compilers and simulators.
Resulting tools run on Windows, Linux and Apple Mac’s. See the, like the Hex format conversion, the KIM-1 Simulator and more.

Assembly toolchain

I have quite a collection of 8 bit computers, 6502, Z80, 6809.
Each processor comes with its own machine language, and for each processor myriads of assemblers have been made, each with its own deviations of the official syntax and way they operate. The simple ones are two-pass assemblers generating binaries and listings and symbol tables. More advanced are made up of an assembler and a linker. Linkers are nice and powerful, but a bit overkill for simple projects. I like command line assemblers, callable from an editor.

Notepad++ Editor
A very powerful text editor, with syntax highlighting, multiple files windows open, good search, plugins like hex editor and external tools support.

  1. Install latest version from the download
  2. Add plugins Hexeditor and NPPEXEC
  3. Add scripts to nppexec such as (requires TASM 2 installed, read below)

    • make6502pap tasm -65 -x3 -g1 -s “$(FILE_NAME)” “$(NAME_PART).pap” “$(NAME_PART).lst” -s “$(NAME_PART).sym”
    • make6502bin tasm -65 -g3 -s -l -fff “$(FILE_NAME)” “$(NAME_PART).bin” “$(NAME_PART).lst” -s “$(NAME_PART).sym”
    • make6502hex tasm -65 -x3 -g0 -s “$(FILE_NAME)” “$(NAME_PART).ihex” “$(NAME_PART).lst” -s “$(NAME_PART).sym”
    • makez80hex tasm -80 -g0 -s “$(FILE_NAME)” “$(NAME_PART).ihex” “$(NAME_PART).lst” -s “$(NAME_PART).sym”
    • etc, see c:\tasm\TASMMAN,HTM
  4. Edit you source
  5. Assembly first time: press F6 choose wanted script
  6. After that Press CTRL-F6 to asemble
  7. The output of the assemble appears at the bottom of the editor in a separate part
  8. Open in Notepad also the listing file
  9. If errors, correct the source
  10. if errorfree, start debugging your code, leave Notepad++ open to edit source and read the listing

TASM32
This is a command line assembler that supports processors like 6502 and Z80. Output is binary, MOS papertape, Intel Hex, Motorola S-record. Listings and symbol tables (for the KIM-1 Simulator) can be generated. Used from Notepad++ as Tool, no need to start from the command line.

  1. Download TASM 32 here
  2. Unpack in e.g. c:\tasm
  3. Create environment variable TASMTABS=C:\TASM
    (Settings – Related Settings – Advanced system settings – Advanced tab – Environment Variables).
  4. Add c:\tasm to the PATH
  5. Invoke tasm from the command line without arguments for help and/or read TASMMAN.HTM in C:/tasm
  6. Add macro’s to Notepad++, see there.

Test and debug
The output of the assembler can be downloaded to the SBC. Burn an EPROM, download hex or papertape. And test the code.

For KIM-1 programs I always use the KIM-1 Simulator debugger on the PC.
Set breakpoints and watches, trace the code, inspect memory, run the program.
When it is a TTY console program, I sue a terminal emulator, Teraterm.
2400 baud 8 bit, one stop bit, no parity, 5 ms character delay, 20 ms line delay for papertape upload.. Higher baudrates may work.

For CP/M there are many emulators available, choose one that allows file from the PC to be accessed also by the emulator. E.g. the Z80 IDE and CP.M emulator of Hein Pragt.
CC65
I only use the assembler and linker of the CC65 package. Mainly for KIM-1 KB9 Basic development, as the source from Pagetable is in this format.

This is how I do it (Windows, can be done also on Linux)

  1. Download and unpack the archive of pagetable in a folder on your PC.
  2. Download and unpack the CC65 package, a C compiler, from which only the assembler and linker is used. I used the Windows binary.
  3. Copy CA65.EXE, LD65.EXE and longbranch.mac from the CC65 package to the folder where you unpacked the MS Basic source.
  4. Change whatever you like in the source. It is quite a complicated construction, with macros for every variant, so look carefully at the listing file what really is produced.
    Start with no adaptations and then go on studying the listing file and testing. The KIM-1 Simulator is a good tool for testing! Load the symbol table file to see what is where.
  5. Assemble and link with this simple batch file makekb9v2.bat, resulting in an object, a binary, a listing file and a symbol label file.
    ca65 -D kb9 msbasic.s -o tmp/kb9v2.o -l tmp/kb9v2.lst
    ld65 -C kb9.cfg tmp/kb9v2.o -o tmp/kb9v2.bin -Ln tmp/kb9v2.lbl
    
  6. Repeat step 4 and 5 until you are satisfied with the adaptations. The article listed above are a good source of inspiration.

Winmerge
A tool to compare files, text and binary. Open the program, drop binary files from the explorer on it and see the differences highlighted. Essential to compare ROM dumps or to check if assembler source assembly leads to identical binary as the original. Detects subtle syntax differences from sources converted or disassembled, leading to different code.

Disassembler
Still searching for a good multiprocessor tool. With some intelligence, like input files not only binary, but also a symbol file and tips of what is data and what is code. Output should be in assembler format ready to assemble. A multipass operation, where you learn from each iteration symbols and data areas.

For 6502 code I use the online tool at Virtual Disassembler. Drop the binary and copy the code. Choose the output format, like “listing” or “assembler”. You can input a symbol file.

6809 Microprocessor Kit

Designed and sold by Wichit Sirichote. Full text and files at his website here. The kit is available for sale, kit or assembled!
Wichit picked the Z80 CPU and designed the microcomputer kit with HEX keys and 7-segment LED displays, and wrote the monitor program.

The 6809 microprocessor kit is a member of the microprocessor kit family (I have also the 6502 and Z80 kit), and share a common design as far as keyboard and LED display and 32K RAM concern, in a format comparable with the Microprofessor 1b.
This kit has hardware serial (68B50) UART at 19200 baud, a big step up from the software serial bit banged slow 2400 baud in the other kits.

6809 Microprocessor kit

Designed and sold by Wichit Sirichote. Full text and files at his website here. The kit is available for sale, kit or assembled!
Wichit picked the Z80 CPU and designed the microcomputer kit with HEX keys and 7-segment LED displays, and wrote the monitor program.

The 6809 microprocessor kit is a member of the microprocessor kit family (I have also the 6502 and Z80 kit), and share a common design as far as keyboard and LED display and 32K RAM concern, in a format comparable with the Microprofessor 1b.
This kit has hardware serial (68B50) UART at 19200 baud, a big step up from the software serial bitbanged slow 2400 baud in the other kits.

6809 Microprocessor Kit 2017
6809 kit User Manual
Monitor source
Programming book
Programming book V2 2020
Quickstart
Schematocs 6809 kit
PLD for 6809 kit
10 ms tick circuit
6809 CC compiler/assembler
V3 PLD and ROM
6809 tools (compiler assembler)
6809 monitor V2
New monitor V1
New monitor
Monitor V3
post

Convert to Papertape V2.2

On the Utilities page I have two programs to convert to MOS Technology papertape format: KIMpaper, a command line utility, and ConvertHexFormat, a GUI app.

All in Freepascal/Lazarus source format, and tested on Linux (Raspberry PI OS) and Windows 10 64 bit. So the programs will run everywhere Lazarus is available (MS DOS, WIndows, Linux Mac OS).

KIMPAPER  is written at the time the Micro-KIM appeared. CLI utility.  Supports Binary to/from Papertape.  Still runs fine on all platforms supported by Freepascal (Windows, MS DOS, Linux etc) after a recompilation, source available.

ConvertHexFormat is a more recent GUI utilitilty with many more 8 bit hex formats as input and output.

There were some bugs of course in older versions. V2 added the ability for multipart hex formats, records having a non-consecutive load address. That seems to wok fine since V2.1
In 2.2 a bug in MOS Papertape format for bigger files is fixed, the end-of-file record (record type 00, total line count) had a bug in the checksum calculation. KIMPAPER is and was correct in the calculation.
But in ConvertHexFormat it was wrong (as it still  is in the well known srec utility in the Unix world!).

post

PC utilities updated

The PC utilities page has seen an update of th4 Conversion hex formats utility.

Programs to manipulate the binary and hex formatted files of interest for SBC owners. Intel hex, MOS papertape, Motorola S-record, binary, hex conversion fort eh 8 bit world.
Runs on Windows, Linux, Mac due to Lazarus and Freepascal. Source included.

post

SerialTester

A program, SerialTester,  a guide and test results.

Also updated Prolific PL2303HXA driver misery solution.

Serial USB adapters testing


So I have a collection of those USB to serial adapters, some with cables and DB-9 connectors, some with cable and Dupont connectors, and some USB TTL type connectors on a PCB with male or female Dupont pin connectors for USB-A, mini or micro USB. Most not documented or unsure if the voltage levels are 3.3V or 5V ..

First some background. These are all descendants of the EIA RS232 standard in some way. Terminology, asynchronous serial format, voltage levels, start bits, stop bits, 7 or 8 data bits, hardware and software handshake, and the way it is abused in many of these devices. And so common nowadays in Arduino and ESP8268, ESP32 and even Raspberry Pi world.

If you are new to the serial world and want to use these devices and understand how, study the next chapter. You will learn and know what I am talking about: DCE, DTE, DSR, DTR, TxD, RxD, CTS, RTS, DTR, RI, CarrierDetect, UAR/T’s, TTL voltage levels being reverse to RS232 voltage levels, a ‘0’ being negative RS232 voltage up to 15V, a ‘1’ being as low as -15V.

 

RS232 asynchronous information


This picture shows where RS232 came into being about 50 years ago,


Read these PDF’s:
RS232 Protocol – Basics
EIA RS232-C Standard Protocol
EIA RS232-E Standard Protocol
Fundamentals of RS–232 Serial Communications
RS232 Physical Layer Interface Standards
RS232 (TIA/EIA-232-F)
RS-232: Serial Ports

USB Serial TTL devices

These little devices came into use to communicate with small computers like SBC’s, Arduino and ESP’s and PC’s. Throw out the overhead of the + and -15v, limit or leave out the handshake signals, (mis)use the DTR signal to reset the Arduino, use it to download firmware or collect data from sensors on the small computers and process it on bigger machines. And act as the power supply the little computer.
Based on special UAR/T IC’s, very small footprint, and dirt cheap.

Testing USB Serial TTL adapters

What you need:
– A PC, Raspberry Pi or another Linux or Windows PC. Any PC platform supporting USB ports will do.
– The program SerialTester, see below
– A small breadboard
– A collection of Dupont cables with male and female connectors
– A multimeter, a most simple one will do

SerialTester

Testing USB serial adapters is not that difficult, you need a terminal emulator, which are available in lots of formats and capabilities. Putty, Minicom etc all allow to choose a serial port, set baudrate and other parameters like hardware handshake, software handshake, number of data and stop bits. With a loopback test (which means connecting serial out TxD to serial in (RxD) you can test the serial connection by typing characters and seeing the characters appear on screen.

What I miss in these programs is a way to inspect the modem control lines. So I wrote a little program for that.
SerialTester allows to do the loopback test and shows the state of the modem control lines.
You can change the DTR and RTS lines since these are set of cleared by the USB serial port. The other lines are read from the USB serial adapter.

Get the program here:
Windows 10 installable executable
source (Lazarus + Freepascal) and executable for Windows, Linux and executable for Raspberry Pi

Use the program as follows to completely test and document (write down test results on the next steps!) the adapter.

1. It is a GUI/Windows program, so start as usual on your operating system. Raspberry runs this program fine, but Linux is not so forgiving in plug and play of USB devices, so expect some hangs and reboots. CH340 chipsets can have a temper, and SerialTester sometimes fails, where Minicom succeeds.

2. Insert the USB adapter, do not connect anything yet to the adapter
For the USB-A types it is handy to have an USB-A male -female cable to bring the adapter to the table

– Check if the USB adapter is recognized by the operating system
For Windows start Device Manager and look for COM Ports, like COM8 in the example below
On Linux start a terminal and type “lsusb”, insert the USB serial adapter and look for added USB device serial adapter, in the screenshot an FTDI adapter.
The command “ls -l /dev/ttyUSB*” will show devices like “ttyUSB0”.

3. Click Port settings and click in the field Port drop down button. A list of serial adapters will be shown, pick one. Note that on a Raspberry the serial port ttyAMA0 on the GPIO connector will be shown also. Here we want the ttyUSBxx device.

Select 300 baud as baud rate, this will help seeing the transmit with the multimeter., leave the rest default.

Press OK

4. Open the Port by clicking the button Open Port. Look at the status displayed, it should tell the port is opened. If not opened, you might have a driver problem, see the sections below on CH34x, FTDI and Prolific 2303HX devices.
You will also see the DTR and RTS fields light up red, as opening also sets the DTR and RTS pin high.

5. Switch on the multimeter and read the prints on the USB or the color of the wires.
– First find Gnd. Indicated with the label GND or a black wire.
– Now find Vcc, indicated with VCC or the red wire. Measure the voltage, should be 5V, 3.3V. Some adapters have a jumper to select the voltage. Some adapters also change the voltage on the other lines, some do not. Measure!

6. Find the TxD pin. Connect the multimeter to the TxD pin. It should be +3.3V or 5V. Also check if changing VCC to +3.3V or 5V makes any difference, some adapters do, some do not change the voltages on the pins.

7. Enter a long string in the Send field, and press Send (or Send CR for a line ending). Observe the readout on the multimeter, it should be lower than the value in rest. Nothing will be shown in the received fields.

If not, then this is not the transmitting pin. Check RxD if that is the transmitting pin, for all my adapters it was TxD, but who knows what manufacturers do ..

8. Inspect the adapter for a DTR line if any. Connect the multimeter to the corresponding pin and measure the voltage. Press the DTR button in SerialTester and check if the voltage changes on the pin.


9. Repeat for the RTS line.

10. Locate the RxD line. Connect this line to the TxD pin and send a string again. Now you should see the Receive and Receive hex fields filled with the send string.

11. Now if any pins are not tested yet, they have to be the other modem control lines. The labels on the adapter will tell or experiment and measure. Connecting to ground or VCC with a 2k2 resistor (to be safe) will show on the display of the SerialTester program the corresponding level.

Chipsets: FTDI, Prolific, Silicon Labs, CH340

The USB Serial adapters contain a UAR/T IC, made by a small group of manufacturers.

1. FTDI. Comes with the highest recommendations. Many types. Well supported in Linux and Windows.
Due to fake IC’s made in China the current drivers check and try to make a fake inoperable.
If you encounter in Windows a non-working FTDI adapter, you cna only use it in Linux, after ‘repairing it. See here how to do that

2. Prolific. Supported in Linux and Windows.
Also due to fakes, older (not fake!) IC’s made by Prolific are not supported by the current Prolific driver in Windows. Device manager shows PL2303HXA PHASED OUT SINCE 2012. PLEASE CONTACT YOUR SUPPLIER.

Easy to solve with an older version of the drive, like in this archive. Unpack in a folder, Update driver, Look on this PC, Have disk, Browse to the folder.
Windows may ‘update’ the driver again, just rollback the update in Device Manager. For permanent fix, see also this page how to enable group Policies on Windows 10 Home and prevent any updates.

3. CH34x. I sometimes encounter problems under Linux with this chipset. Windows runs fine.

Reports

‘Blue’ closed connector with cable
Prolific PL2303
Male Dupont connectors
Black Gnd
Red +5V
Green Tx (sending data) 3.3V
Yellow Rx (receiving data)
Betemcu CH340
Status LED red, send LED blue
Edge pin connector maleGND Gnd
VC +3.V or 5 V slide switch
TX 5V Sending
Rx 5V receiving
DTR 5V
CTS connect ground for ‘on’
Button switch of Vcc
D-Sun-V3.0 CH340
Status LED red Send blue led Received blue led
Edge pin connector male
GND Gnd
RxD receiving
TxD sending at 3.3V or 5V
3V3 3.3V
Vcc jumper to +3.3V or 5V (no jumper 3.3 V)
5V 5V
Tienu ZX2H1911A1 PL2303HXA
Status LED red Sending green LED Receiving Yellow LED
Edge pin male
5V 5V
3.3V 3.3V
TxD sending 3.5V
RxD receiving 3.5V
Gnd Gnd
FTDI DCORSO FTDI 232
Red status LED send receive green LEDs
Edge pin male
Jumper +5V Vcc +3.V
Jumper 5V – Vcc – 3.3V
All modem signals to edges RI CTS RTS
110 baud not supported
DTR 5V or 3.3V following jumper
TX sending 5V or 3.3V following jumper
RX receiving 5V or 3.3V following jumper
VCC 5V or 3.3V following jumper
CTS 5V or 3.3V following jumper
Gnd Gnd
4D Programming Cable CP2102
Dupont female
RES ?
Gnd Gnd
Tx Sending 3.4V
Rx Receiving 3.4V
+5V 5V
FTDI cable no ident,
lights in cable red (receive) green (send)
Dupont female
Black Gnd
Blue CTS 3.4V
Red +5V
Green Sending 3.4V
White Receive 3.4V
Yellow RTS 3.4V
Tienu FTDI232H
USB-A FTDI edge pin red status LED green send, yellow receive
GND Gnd
RXD Receive at 3.5V
TXD Sending at 3.5V
3.3V 3.4V
5V 5V
FDTI basic Sparkfun female dupont bottom
Mini USB
GND Gnd
CTS 5V
5V 5V
TxD sending 5V
RXI receive 5V
DTR 5V
Square CP210X Red status
LED Red LED send Red LED receive
Micro USB Male Dupont Edge
3V3 3.3V
DTR 3.4V
RXD sending 3.4 V
TXD receive 3.4V
GND Gnd
+5V 5V
FTDI232 Mini USB
Jumper 5V – Vcc – 3.3V
All modem signals to edges. Voltages follow Jumper setting.
MBC2 cable Prolific 2303
black GND
red 5V Vcc
Green TX sending at 3.4V
White Rx
UC-2102 Cable CP210X
Male edge pin connector
DTR 3.4V
RxD
TxD sending 3.4 V
+5V +5V
GND
GND

 

post

Convert hex formats V2

A program to convert between hex or binary files for 8 bit systems with a 64K address space.
V2 adds the Wozmon Apple 1 format and allow multipart Intel Hex, MOS Papertape and Motorola S records.