# Configuration (Draft)

# Overview

In order to run any applications, you will need to activate a virtual ROM (eg. to run BASIC, or boot a floppy disk) and maybe load an operating system (such as CDOS or Cromix) from a virtual disk.

Also like the original computer, your Cromemco Z-1 has no video output port. Owners of the original Cromemco Z-1 would connect a serial terminal (either a teletype printer or visual display unit) to a serial port. While you can still do this (see Serial Communications section), this modern kit offers a much easier solution using Wi-Fi.

Once power is applied to your kit, the ESP32 will create a Wi-Fi Access Point. You can connect your computer to this Wi-Fi network as if it were connected to a Wi-FI router. You can then open a web page, the Desktop UI, that will give you full access to the Cromemco Z-1 - including a virtual serial terminal (TTY:), floppy disks, printer (LPT:) and more.

Once connected, you can then configure the Cromemco Z-1 to connect directly to your home Wi-Fi, so you can use it without having to change your Wi-FI settings again.

# Getting connected

• Plug in the power to the Cromemco Z-1 kit.
• On your computer, open the Wi-Fi settings and select the cromemco network (SSID).
• When prompted for a password, enter password.

Your computer should now be connected, and you will be able to open the Desktop UI. The web interface has been written and tested with the Chrome browser in mind, and you might find it works differently if you are using a different browser.

• If you have a Mac, open your browser and enter cromemco or cromemco.local as the web address.
• If you have a PC, open your browser and enter cromemco or 192.168.4.1 as the address.

# Default configuration

# Cromemco Z-1 (guest)

• RAM is 64K occupying the entire address space from 0000h to FFFFh
• CPU is Zilog Z80 @ 2MHz with support for undocumented op-codes
• No boot ROM is active by default

# ESP32 (host)

• Wi-Fi set to Access-Point (AP) mode with the default SSID of cromemco, password of password
• Hostname (HOSTNAME environment variable) set to cromemco (cromemco.local for mDNS)
• Port (PORT environment variable) set to 80
• Timezone (TZ environment variable) set for AEST+10, ADST+11 (ie. Sydney, Australia)
• Time server (NTP_SERVER environment variable) set to pool.ntp.org
• POST (Power On Self Test) disabled
• Console log level set to NONE (details to follow)

# Startup configuration (Non-Volatile Storage, NVS)

The startup configuration is modified via the toggle switches on the front panel.

To enter startup configuration mode, follow the sequence:

1. ensure the ESP32 is connected to a USB power source, the red LED on the ESP32 board should be illuminated
2. turn the front panel power switch off, PWR OFF, the down position
3. hold the EXAMINE toggle in the Examine, up position
4. press and release the Reset buttons while holding the EXAMINE toggle up
5. hold the EXAMINE toggle for a second or two
6. release the EXAMINE toggle

The Cromemco Z-1 should now be in startup configuration mode. This is indicted by a running LED pattern (right to left) on the 4 LEDS at the right hand side of the front panel (HOLD, WAIT, RUN, INTERRUPTS ENABLED).

To set the startup configuration mode value, follow the sequence:

1. To set a bit, put the corresponding Address toggle switch in the up position.
2. To clear a bit, put the corresponding Address toggle switch in the down position.
3. Raise the DEPOSIT toggle to the Deposit, up position to store the entered startup configuration value.

# Serial Communications (RS232, USB)

The Cromemco Z-1 is configured with three (3) virtual TU-ART UART devices.

The first virtual UART is the console port on the Cromemco FDC16/64 floppy disk controller. The second and third virtual UARTs are the A and B devices on the Cromemco TU-ART serial/parallel I/O interface.

The board/port/devices are assigned as follows:

When the machine boots, the virtual TU-ART 0A is routed to the physical UART0 on the ESP32-PICO-KIT.

• This enables you to use any software on the Cromemco Z-1 that communicates via this UART as the console using a terminal or terminal emulator depending your method of connection.
• The default speed with the current firmware is 115200 baud @ 8N1

# Serial UART over USB

The ESP32-PICO-KIT supports serial communications from UART0 over USB. It uses a Silicon Labs CP210x USB to UART bridge

1. connect the ESPP32-PICO-KIT to a PC using a suitable USB cable
2. start a terminal emulator on the PC set for 115200 baud 8N1 connected to the serial device your OS identifies the ESP32-PICO-KIT on
   • Windows will be a COMx: port
   • OSX will be /dev/tty.SLAB_USBtoUART
   • Linux will be /dev/ttyUSB0 (or similar, TBA)

Additional information is available from the Espressif (manufacturer of the ESP32-PICO-KIT) web site at https://docs.espressif.com/projects/esp-idf/en/latest/get-started/establish-serial-connection.html

# Serial UART over RS232

Serial UART over RS232 is configured by using the supplied jumpers/shunts to bridge the required pins on the Patch and Comms headers accessible on the rear of the PCB, and connecting a suitable RS232 device to one of the DE-9M connectors labeled RS232-1 and RS232-2

RS232 line levels are provided by the Maxim MAX3232 IC see the data sheet for details.

You must position 4 of the jumpers/shunts provided to enable a Serial UART over RS232. This image shows the currently supported configuration for the jumpers/shunts on both the Patch and Comms headers for UART0 to RS232-1

# UART0 to RS232-1

# Patch header

• bridge Tx - T1 - vertical position second from right
• bridge Rx - R1 - vertical right most position

# Comms header

• bridge @ Tx1 - horizontal second position from top
• bridge @ Rx1 - horizontal fourth position from top

# UART1 to RS232-2

# Patch header

• bridge IO22 - T2 - vertical position third from right
• bridge IO5 - R2 - vertical position fourth from right

# Comms header

• bridge @ Tx2 - horizontal third position from bottom
• bridge @ Rx2 - horizontal last position at bottom

# Configuring physical UART parameters (speed, data & stop bits)

You can configure the parameters for both UART0 (RS232-1/USB) and UART1 (RS232-2) via the boot.conf file.

See UART Configuration in the boot.conf file below, for further details.

# Wi-Fi Communications

The ESP32 has on-board Wi-Fi and can boot in either Access Point (AP) or Station (STA) mode. The mode is determined by the NVS_IF_STA bit in the startup configuration stored in NVS and described above.

• In AP mode, the ESP32 acts as an Access Point and broadcasts a system defined SSID and provides DHCP services for clients to connect
  • The SSID hardcoded in the firmware is espressif with a password of password, this will only be used if the boot.conf file on the microSD card cannot be read or does not include a HOSTNAME=name statement, see Boot.conf file below.
  • If a HOSTNAME=name statement is found in the boot.conf file, then this hostname is also used as the SSID in AP mode. In this case, the password still remains password
• In STA mode, the ESP32 acts as a Wi-Fi station or client and can join an existing Wi-Fi network (supporting WPA or WPA2, but not Enterprise WPA).
  • The SSID and password of the desired Wi-Fi network must be configured in the boot.conf file using the SSID=name and PASSWORD=password statements, see Boot.conf file below.

# Boot.conf file

The boot.conf file is located on the microSD card with the path /cromemco/conf/boot.conf As the ESP32 boots this file is loaded, each line parsed and the variable=value pair is added to the environment (like posix environment variables).

# Default boot.conf

The default configuration, as shipped (in Release v1.10.0-beta.1) is a follows:

### Network configuration
NTP_SERVER=pool.ntp.org
TZ=AEST-10AEDT,M10.1.0,M4.1.0
HOSTNAME=cromemco
PORT=80
SSID=mySSID
PASSWORD=myPASSWORD
WIFI.sta.scan=1
#WIFI.password.hide=1
### UART configuration
#UART0=115200,cs8
#UART1=115200,cs8
#UART2=115200,cs8
### Performance parameters
#TTY.netsrv.buffer_delay=33
#TTY2.netsrv.buffer_delay=33
#TTY3.netsrv.buffer_delay=33
#LPT.netsrv.buffer_delay=33
### Harddisk images
#HARDDISK.hd0=hd0.hdd
#HARDDISK.hd1=hd1.hdd
#HARDDISK.hd2=offline
### TU-ART default device mappings (HAL)
#TUART0.deviceA.device=WEBTTY,MODEM,UART0
#TUART1.deviceA.device=WEBTTY2,SCKTSRV1,UART1
#TUART1.deviceB.device=WEBTTY3,SCKTSRV2,UART2
### Modem initialization string
MODEM.init=ATS0=1S15=1&A1 #S0=1 auto-answer after 1 ring, S15=1 enable telnet protocol
#MODEM.init=ATS15=1 #S15=1 enable telnet protocol

# Network Configuration

The Network configuration entries should be familiar and mostly self explanatory.

# UART Configuration

The UART configuration entries define the speed, data & stop bits for the three physical UARTs on the ESP32, UART0, UART1 and UART2

For example:

### UART configuration
UART0=115200,cs8 # ie. 115200, 8N1 - not required because this is default
UART1=9600 cs7 cstopb parenb parodd # ie. 9600, 7O2

• parameters can be separated by spaces or commas
• parameters are case insensitive
• parameters follow the convention used by the screen program under unix/linux/gnu ie.:
  • default is 115200,cs8 in other words 115200 8N1
  • standard baud rates from 110 to 230400 e.g. 110, 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400 others may work, but you'll have to experiment
  • cs7 - for 7 data bits
  • cs8 - for 8 data bits
  • cstopb - for 2 stop bits, default is 1
  • parenb - for even parity, default is none
  • parenb,parodd - for odd parity

# Performance parameters

The Performance parameters exist only for the four devices TTY: (default: TU-ART 0A), TTY2: (default: TU-ART 1A), TTY3: (default: TU-ART 1B)and LPT: and apply only to websocket communication to the Desktop UI

They specify a time in milliseconds (ms) during which output to the device will be buffered (up to the next line feed character) and transmitted in a single (websocket) packet. This can greatly improve performance of both the TTY: and LPT: devices. If used, recommended optimal settings are:

#Performance parameters
TTY.netsrv.buffer_delay=33
TTY2.netsrv.buffer_delay=33
TTY3.netsrv.buffer_delay=33
LPT.netsrv.buffer_delay=33

# Harddisk image

Three (3) harddisks are supported with the virtual Cromemco WDI-II winchester harddisk interface.

A harddisk image (~10MB) can be mounted for each of hd0:, hd1: & hd2:

Any online harddisk image is visible on the desktop as HD0:, HD1: or HD2:

Harddisk images are visible in the disk library LIB: and indicated with a harddisk icon. You can drag-and-drop a new harddisk onto the LIB: window to upload a new harddisk image.

The default harddisk image mappings are: (these do not need to be specified in the boot.conf file)

HARDDISK.hd0=hd0.hdd
HARDDISK.hd1=hd1.hdd
HARDDISK.hd2=hd2.hdd

You can specify any haddisk image file in the directory for any harddisk, or specify offline to force a harddisk to be offline

e.g.

### Harddisk images
HARDDISK.hd0=disk1.hdd
HARDDISK.hd1=workdisk.hdd
HARDDISK.hd2=offline

# TU-ART device mappings

A HAL (Hardware Abstraction Layer) enables mapping of character mode devices to the three (3) virtual TU-ART serial devices

• the TU-ART device mapping configuration is loaded and reported to the debug console (UART0/USB) when the Cromemco Z-1 is started/powered-on
• the TU-ART device mapping configuration is also displayed in the SYS: virtual device on the desktop UI
• when no TU-ART device mapping configuration is specified, a standard configuration is the default, and reported as follows:

TU-ART Devices
TUART0.deviceA = WEBTTY,MODEM,UART0
TUART1.deviceA = WEBTTY2,SCKTSRV1,UART1
TUART1.deviceB = WEBTTY3,SCKTSRV2,UART2

the purpose of the HAL is to:

• simplify the addition of new character mode devices in future eg. additional hardware UART; network sockets; additional telnet listeners; new virtual peripherals on the desktop UI
• enable the user to assign specific devices to each of the three (3) virtual TU-ART serial ports
• details of configuring the TU-ART device mapping will be published soon

# Modem initialization string

This string will be processed by the 'AT' Modem when it is initialised and reset (ie. with the command ATZ)

For example, to initialize the modem for:

• auto-answer after 1 ring (ATS0=1)
• enable telnet protocol (ATS15=1)
• enable answer mode (ie. listen) in "daemon" mode (AT&A1)
• with the commands concatenated into a single command string ATS0=1S15=1&A1

add the following line:

#Modem initialization string
MODEM.init=ATS0=1S15=1&A1

# System.conf file

The system.conf file is located on the microSD card with the path /cromemco/conf/system.conf

# Memory maps

The only parameters that effect the Cromemco Z-1 are the [MEMORY n] sections:

# <><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
# memory configurations in pages of 256 bytes
#	start,size (numbers in decimal, hexadecimal, octal)
# up to 7 memory sections allowed
# up to 6 ram/rom statements per section allowed
#
# NOTES:
# - memory sections only effect bank 0 of the machine's memory
# <><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>

[MEMORY 1]
# Memory configuration for running CP/M, CDOS, CROMIX with RDOS0308:
# 256 pages RAM, 32 pages ROM
ram		0,256
rom		0xc0,32,rdos0308.hex
# Power-on jump address for the boot ROM
boot		0xc000

[MEMORY 2]
# Memory configuration for RDOS1:
# 256 pages RAM, 4 pages ROM
ram		0,256
rom		0xc0,4,rdos1.hex
# Power-on jump address for the boot ROM
boot		0xc000

[MEMORY 3]
# Memory configuration for RDOS252:
# 256 pages RAM, 32 pages ROM
ram		0,256
rom		0xc0,32,rdos252.hex
# Power-on jump address for the boot ROM
boot		0xc000

[MEMORY 4]
# Memory configuration for Z1MON 1.0:
# 256 pages RAM, 16 pages ROM
ram		0,256
rom		0xe0,16,z1mon-1.0.hex
# Power-on jump address for the ROM
boot		0xe000

[MEMORY 5]
# Memory configuration for Z1MON 1.4:
# 256 pages RAM, 16 pages ROM
ram		0,256
rom		0xe0,16,z1mon-1.4.hex
# Power-on jump address for the ROM
boot		0xe000

[MEMORY 6]
# Memory configuration for Monitor/BASIC ROM:
# 256 pages RAM, 16 pages ROM
ram		0,256
rom		0,16,mbc.hex
# Power-on jump address for the ROM
boot		0