Zimodem

Zimodem 4.0 (C)2016-2026 Bo Zimmerman Please read the LICENSE file for license information Please read the NOTICE file for credits information

Intro:

This firmware code provides an api for communication between a serial terminal and the ESP8266 or ESP32. It simulates the old-style Hayes "AT" commands, so that the ESP8266 appears to the terminal as if it were a Hayes modem. These "AT" commands may then be issued to the ESP8266 in order to force it to connect to a wireless access point, and from there to make one or more manageable connections to the internet. It also includes a streaming serial "telnet" mode, and server/port listener capabilities.

The default baud rate that the firmware establishes is 1200. Be sure to use the commands below to set this to the proper baud rate for your terminal/host computer. If you plan on using the Commodore 8-bit utilities, keep the firmware baud rate saved at 1200.

Building:

To build this firmware for the ESP-01 or ESP-12, I used the Arduino IDE rev1.8.10 with the 2.7.4 Arduino ESP8266 libraries using the Generic ESP8266 Module. Versions newer than 2.7.4 may not work. Install the libraries from the Boards Manager using http://arduino.esp8266.com/stable/package_esp8266com_index.json. Both versions of the firmware are built with SPIFFS enabled. On the ESP8266, I used settings of 1M/160k, but you may want to alter that depending on your hardware and needs.

To build this firmware for the ESP-32, I also used the Arduino IDE rev 1.8.10 with the Arduino ESP32 Dev Module installed from the board manager * , with the following settings: QIO, 8MB, 80MHZ, 921600, NONE, Avrisp Mk II **.*, and 3MB App space. Currently on library version 2.0.17.

** Before you build, you'll want to go through the file zimodem.ino and configure the various #defines to reflect hardware pin assignments and features. These especially include: INCLUDE_IRCC, SUPPORT_LED_PINS, INCLUDE_SD_SHELL, INCLUDE_OTH_UPDATES, DEFAULT_BAUD_RATE, PIN_FACTORY_RESET, all the various DEFAULT_PIN_* assignments for your hardware, INCLUDE_SSH, and MAX_PIN_NO. In addition, at the top of pet2asc.h is where the default main and debug uarts are assigned (MAIN_UART_NUM). Make sure those reflect your wiring as well.

Using:

Upon initialization, or any time the ESP module is reset, the modem will display its version, and some information about the host hardware, and then read a configuration file from the internal SPIFFS to re-establish the previously set baud rate, and to attempt to re-connect to the previously connected wireless router. The first time it is run, the firmware will set a baud rate of 1200 and display INITALIZED to let you know that no previous wifi configuration was found. Once the serial terminal displays READY, it is ready to receive commands.

AT+CONFIG: The first command you'll probably want to enter is used to connect to a wireless router, and set your flow control and other command mode settings.

Linefeeds: If you plan to use this primarily from a computer that doesn't need linefeeds, such as the C64, you'll want to enter ATR0 to go into carriage-return only mode, and then at&w to save this setting as well.

Baud Rate: If you want to operate at a higher baud, you'll want to enter ATB9600 (or whatever baud rate you want to try), and then reconnect your terminal program to the modem at that new baud rate. If everything looks good, and you want to keep the new baud rate across restarts, save the new baud rate with AT&W. Warning though: Most of the example C64 programs assume the modem defaults to 1200 baud.

AT+PRINT: If you want to try printing to a CUPS/IPP-printer, enter AT+PRINT?:<host>:<port>/<path>, followed by your data. Where ? is A)scii, P)etscii, or R)aw. A 5 second pause in incoming data completes the document and returns to command mode. Example: AT+PRINTR:192.168.1.10:631/ipp/printer -- followed by ENTER and then the data to print, without any pause longer than 5 seconds. Subsequent to doing this, using AT+PRINT will repeat the previous URL.

AT+IRC: If you want to chat on IRC, enter AT+IRC, enter a nickname and a irc host as a phone number entry, then /join channels, chat, or /quit.

AT+SHELL: ESP32 Modem users with SD-cards can enter AT+SHELL to get a shell command prompt. Enter ? to get a list of shell commands.

AT+PING: To check if your wifi is connected and DNS resolution is working, try AT+PING"google.com". An OK means a response was received.

AT+COMET64: For modems with SD-cards, this puts the modem into 2400 bps, CSIP protocol mode for reading/writing directly to the card (for V-1541). +++ to exit.

AT+HOSTCM: For modems with SD-cards, this puts the modem into HOSTCM protocol mode for reading/writing directly to the card (for Commodore SupetPET SP9000). +++ to exit.

AT+1650, 1660, 1670: Puts the modem into a emulation mode for Commodore 1650, 1660, and 1670. Changes baud rates accordingly. Use AT&L or AT&F to clear emulation settings.

AT+SLIP: Puts the modem into SLIP mode (or ATDT5517545). Baud rates under 57600 will not receive broadcast/multicast packets. Reset modem to exit.

AT+PPP: Puts the modem into PPP mode (or ATDT5517546). Baud rates under 57600 will not receive broadcast/multicast packets. Reset modem to exit.

Telnet Dialing: If you want to connect to a remote telnet server, eg coffeemud.net, port 23, you'll want to enter AT&S62=1DT"coffeemud.net:23". Don't forget to set your terminal program to the proper translation mode (ANSI, ASCII, or whatever).

Normal Dialing: If you are using a Commodore Graphics terminal program and want to connect to a Commodore BBS, or a standard ASCII terminal program for a non-Commodore BBS, you'll want to enter e.g. ATD"cottonwoodbbs.dyndns.org:6502". The "T" in "ATDT" is optional if register 62 is 0 (default).

Q-Link Setup: If you want to use Q-Link, you need to add a phone number alias first. To do this, enter ATP"5551212=q-link.net:5190" or enter it from the config menu AT+CONFIG. From the C64 Q-Link client, select "Hayes compatible" 1200 baud modem when prompted.

BBS/Port Listeners: If you want to run a Commodore BBS program using the modem, you'll want to configure the BBS program to the same idle baud rate that your modem is using (1200 baud by default), configure it for a Hayes style modem (or the C=1670), and either create a persistant listener using AT+CONFIG, or use an initialization string of "ATR0E0S0=1S41=1A6400" plus any other recommended settings from the BBS program. This creates a listener at port 6400 that switches directly to stream mode on the first ring, with no linefeed carriage returns, and no keystroke echo. Your BBS program may require you add certain other settings, such as V0 or X1.. which you should also do.

Command Set:

The command set is as follows (not case sensitive):

ATZ : closes all open socket connections (preserving the Access Point connection), stops all listeners, and resets the state of the Command processor to the saved configuration, preserving the current baud rate and wifi connection.

A/ : Repeats the previous command

ATI : re-shows the startup message, including wifi connection information. ATI0 : same as ATI ATI1 : Shows the current common variable settings, common 'S' registers. ATI2 : Shows the modem's current IP address ATI3 : Shows the modem's current Wireless Router connection ATI4 : Shows only the firmware current version ATI5 : Shows all the current variable settings, all 'S' registers. ATI6 : Shows the current mac address. ATI7 : Shows the current formatted time (see AT&T). ATI8 : Shows the firmware build date/time ATI9 : Same as I3, but also includes any static settings, same order as ATW ATI10: Shows the last printer url used.

ATA : If a server listener has generated a RING, then ATA will switch the last rung connection to Stream mode (see ATD).

ATAn : Causes the modem to create a server listening on port n. When a connection is received, the terminal will generate 1 or more RINGs according to the ATS0 register, followed by a normal CONNECT respose. At this point, all other commands related to connections may be used normally, unless ATS41 is > 0, in which case incoming connections are automatically sent to Stream mode as per ATD or ATA. Listeners are listed along with other connections using ATC0. ATAPn : Adding a P modifier causes all incoming connection input to be translated to PETSCII ATATn : Adding a T modifier causes connection streaming input to be translated per TELNET when the changed to Stream mode ATAEn : Adding a E modifier causes connection terminal echo to be enabled when the changed to Stream mode ATAXn : Adding a X modifier causes connection XON/XOFF flow control to be enabled when the changed to Stream mode.

ATN0 : Shuts down all listeners, leaving client connections open ATNn : if n > 0 then closes a Server (ATA) listener with the given id; does not close any connections received from that listener.

ATE0 : Turns serial terminal echo off for command mode. ATE1 : Turns serial terminal echo on for command mode.

ATV0 : Turns off verbose responses mode (Uses Terse Numeric response mode) ATV1 : Turns on verbose responses mode (Uses Word response mode)

ATX0 : Turns off extended response codes (1/CONNECT instead of 5/CONNECT 2, etc..) ATX1 : Turns on extended response codes (5/CONNECT 2 instead of 1/CONNECT, etc..)

ATF0 : Turns on rts/cts flow control. ATF1 : Turns on xon/xoff flow control. ATF2 : Turns on xon/xoff flow control, sets XON mode (if necessary), and, in command mode, will immediately go to XOFF when a single connection packet is received. This is very useful when the client wants to ensure it only receives one packet to process. You can think of this as an alternative way to use xon/xoff by having XOFF automatic between packets. ATF3 : Similar to ATF2 except that the defaul