ESP8266 Altair 8800b Emulator V 0.95 introduction This document will describe the construction, programming, and operation of an ESP8266-based system that will emulate the Altair 8800b (the front panel-less version of the famous Altair 8800). It is capable of running the Altair versions of CP/M 2.2 and in addition, the original version of "Micro Soft" MITS Basic 3.2, written in part by Bill Gates himself, via a serial or raw Telnet connection. The TCP/IP wireless connectivity supports FTP and over the air firmware updates. The system can act as a standalone access point or connect directly to your network. Audience The reader of this document is expected to be fairly knowledgeable in the Arduino IDE, the ESP8266, and in serial/TCP/IP communication, and is familar with tools used for that communication. If you are not familiar with CP/M or BASIC, there is a great deal of material on the Internet available that will help. Hardware This is a very simple hardware design, so those with any experience withthe ESP8266 will have no problems duplicating this from a description of the circuit. It is expected that you have a working ESP8266 ESP-12E with USB/serial connectivity that you can program via the Arduino environment, having RESET and PROGRAM buttons/switches. The ESP-12E model is REQUIRED because it has 4M of flash ROM. It is very difficult to visually determine the size of flash on these devices, but software exists so that the flash size can be verified. The older 512k or 1M flash devices are NOT suitable for this project. From that point, you will also need three LED's, three 300 ohm resistors, and a Microchip 23LC512 64K SPI RAM (do not substitute with a SPI RAM of lesser or greater capacity). Connect as follows: LED's via the 300 ohm resistors (active high) to: GPIO 16 (representing the "power" LED) GPIO 4 (representing the "Disk A" activity LED) GPIO 5 (representing the "Disk B" activity LED) Now, connect the 23LC512 as follows: Pins 7,8 to 3.3v Pins 3,4 to GND Pin 1 to ESP8266 GPIO0 (as chip select) Pin 2 to ESP8266 GPIO12 (as MISO) Pin 5 to ESP8266 GPIO13 (as MOSI) Pin 6 to ESP8266 GPIO14 (as CLK) The serial I/O can be accomplished to your liking. Because I prefer serial RS-232 directly and program with an RS-232 to USB dongle/cable, I use an RS-232 level shifter on my boards and connect with a DB-9 cable. Remember to provide good, clean and sufficient power to the ESP8266. _Many_ mysterious problems with wireless can be traced to inadequate or poorly regulated power. Ask me how I know this. Programming The Arduino program environment is used; the following settings/features are required. 1. 160Mhz 2. 80Mhz flash, DIO (QIO may work) 3. SPIFFS, split at 1M programming, 3M SPIFFS 4. You need to add the "SPIFFS uploading feature" to the Arduino environment. Code The code provided is open-source and is licenced under GPL. The "important" part of it was written by Dan Karling and is available on GitHub under dankar. Other libraries have their own restrictions. Special thanks to igrr, me_no_dev, and dankar. The code I have added is highly unoptimized and is generally a poor example of coding compared to the rest of it...but it DOES work. I don't do this for a living. My part of the code is provided under an "NDA" clause - No Disparagement Allowed! You are, however, welcome to improve it. You will probably have to add several libraries to your system. The FTP library I used is a at https://github.com/nailbuster/esp8266FTPServer. The "data" directory provided in the code is empty. This is because this directory should contain the CP/M, Zork, and other files required for operation. These were acquired from various sources on the Internet and you will need to acquire them. Places would include http://schorn.ch, http://altairclone.com, and others. A big thanks to the people who run these websites and acquired these classic images. The left column is the description of the file: the right column is what the file MUST be named (with case as shown below) in your project's data directory file: 88dskrom.bin ---------> 88dskrom.bin 88dskrom.bin ---------> g_88dskrom.bin cpm22b-63k.dsk--------->cpm22b-63k.dsk (or ordinary CPM 2.2 for Altair is OK) cpm22b-63k.dsk--------->g_cpm22b-63k.dsk zork--------->disk02.dsk zork--------->g_disk02.dsk supercalc--------->supercalc2.dsk supercalc--------->g_supercalc2.dsk games--------->games1.dsk 4K Altair Basic 3.2----->4kbas32.bin 4K Altair Basic 3.2----->g_4kbas32.bin You MUST have these files in the DATA directory. These files MUST exist in the data subdirectory of this project, so that the Arduino IDE based SPIFFS uploader will find and upload them properly. Programming Firstly, upload the files listed above to the ESP8266. This is a slow process. Then, you may program the chip. Communications Tools The Arduino IDE is not a suitable "terminal" for this project. Although it isn't perfect, I recommend "TeraTerm" (Windows) for serial communication, and PuTTY for TCP/IP. For Apple tablets and phones, I heartily recommend Attachmate's Telnet client. For Android, i have had good luck with JuiceSSH. FileZilla is the only tool recommended for FTP mode (with ONE simulataneous FTP transfer only). Acquire these tools from original, reputable sources only (be careful with what link comes up on Google). Some of these tools are known to have been hijacked and had malware/spyware/viruses wrapped around them!!! Some notes: 1. TeraTerm occasionally goes haywire when the ESP8266 changes baud rates. Resetting the terminal or restarting TeraTerm will clear this up. 2. Note that all TCP/IP clients should operate in RAW mode. 3. Windows based Telnet clients (PuTTY) don't perform as well in throughput. I suspect that this may have to do with the Windows stack itself not handling large numbers of packets well or quickly. TCP/IP was not really designed for single-character communication. Nonetheless, Attachmate's Reflection (R) software on IOS performs brilliantly under these conditions. And, on IOS, it's free at this moment. 4. When possible, select VT100 emulation. 5. "Raw" Telenet character programming: The DEL key is the BACKSPACE. No echo. CR=CR; LF=LF. 6. Serial Programming: The DEL key is the BACKSPACE. No Echo. 8 data bits, 1 stop bit, no parity. CR-CR; LF=LF. Operation The program creates a "settings" file if none exists (which it won't upon initial start-up). It will commuinicate serially at 300 baud,n,8,1, so adjust your serial port to this speed. You will be presented with this menu: MITS Altair 8800b Emulator 0.9x (64K RAM, serial, dual MITS 8 inch disk system) Select from menu: 1. CP/M, Zork 2. CP/M, Supercalc 3. CP/M, Games 4. Altair 4K Basic 3.2 A. Refresh Corrupted Virtual Images B. Adjust TCP/IP Timeout (now 5 min) C. Restart Host, Use RS-232 Instead D. Adjust Serial Baud (now 300) E. Set Terminal Type (now TTY) F. Select AP Mode or Client Mode WIFI For Emulator (now AP) G. Enter New Router Connect SSID/Password H. Enter New Access Point SSID/Password I. TCP/IP Lockdown mode (Unlocked) Each of these items will be covered in detail. CP/M, Zork This will load a CP/M 2.2 image as drive A, with Zork as B. CP/M, Supercalc This will load a CP/M 2.2 image as drive A, with Supercalc as B. CP/M, Games This will load a CP/M 2.2 image as drive A, with games as B. Altair 4K Basic 3.2 This will load the original MITS 4K Basic. Heed the notes printed before it runs. If the system running in RS-232 mode and is not "locked down" over TCP/IP mode, the following are also accessible: Refresh Corrupted Virtual Images Earlier in this manual, you may have wondered what the "g_" files were for. In the event of flash disk corruption or BDOS errors on CP/M due to incomplete writes (from, for example, a power failure or unexpected reboot), "g(olden) copies of the files are written over the potentially damaged files). Do NOT interrupt this process. Adjust TCP/IP Timeout Restart Host, Use (TCP/IP/Serial) Instead This toggles the 8800b between Serial and TCP/IP modes. This will be described later. Adjust Serial Baud The available baud rates are 300, 1200, and 9600. note that any change will cause a reboot. Read the note above concerning the behavior of TeraTerm when changing baud. Set Terminal Type The available types are: 1. TTY (straight teletype) 2. TTY with delay. This is included to support old teleprinters with very slow carriage returns. This works on my teleprinter; you may want to adjust the code to work properly with yours. 3. VT100. All this is is a means to clear the menu screen. IT is VERY limited in VT100 support. Select AP Mode or Client Mode WIFI For Emulator This selects Access Point or Client mode for TCP/IP use. Basically, the program can either configure the ESP8266 to be a standalone access point with its own SSID, password, and network, or it can connect to a preexisting network (your network, for example). Enter New Router Connect SSID/Password This allows you to enter the SSID/password of a preexisting network (i,e,YOUR network) so that the 8800b can join it. Note that the passwords MUST be >8 characters long. The ESP8266 does NOT like passwords of less than eight characters. Enter New Access Point SSID/Password This allows you to enter the SSID/password for standalone AP operation. Note that the passwords MUST be >8 characters long. The ESP8266 does NOT like passwords of less than eight characters. TCP/IP Lockdown mode When operating in TCP/IP mode, this "locks down" all of the other settings so that they cannot be modified via TCP/IP connection. This is recommended when performing a public demonstration. Hidden Menu Items There are two "hidden' menu items, "+" and "-". These are accessible via RS-232 operation ONLY. The "-" (Code Update) This utilizes the OTA programming library for Arduino/ESP8266. The program configures an access point with SSID of i8080-XXX (XXX being derived from the Chip ID of your ESP8266) and a password of "edroberts". These are fixed and not changeable from the CLI. Should you wish to utilize this after inital programming, locate the .BIN object code output from the Arduino IDE, and, using the update page located at 192.168.1.1/firmware, upload the code. DO NOT INTERRUPT or you might "brick" the unit and it would have to be reprogrammed in the conventional manner, via the Arduino IDE. Note that NO error/sanity checking is done on this code. This method of updating is not secure and you are advised to not leave the unit in this state for any period of time (see Security) The "+" (FTP Mode) Should you wish to replace to back up CP/M disk or other images, the software can be placed into an FTP server mode. Note that this works properly ONLY with "FileZilla". Again, the ESP8266 is configured in AP mode, with SSID of i8080-XXX (XXX being derived from the Chip ID of your ESP8266) and a password of "edroberts". These are fixed and not changeable from the CLI. This is very insecure, and you are advised not to leave the unit in this state for any period of time (see Security). Use Cases: 1. RS-232 only You might want to use this strictly to work with (USB) RS-232 only. In this case, set the baud to your liking. Select the terminal type (you MIGHT have a slow teleprinter, in which case "2" is recommended). Set up the serial device as described earlier for the terminal/Telnet programs. In my case, I built in a TTL/RS-232 converter and I run a 40+ year old ADM-3a terminal from this tiny assembly. 2. Standalone Wireless You might like to use the device wirelessly OR via RS-232 on its own network. So, enter the Access Point SSID and password for the wireless system (note, it is impossible to make an "open" system, and the password NEEDS 8+ characters). You MIGHT want to "lockdown" TCP/IP if you are not the only user, and you might want to restrict use to 5 minutes of inactivity if you are demonstrating this to other people. So, after this, flip the unit to AP mode as described earlier, and then restart via the menu item to TCP/IP. Now, connect to the new wireless network, and connect via raw TELNET on port 23 to 192.168.1.1. When you disconnect, the system will reset and be ready for a new connection. There can be only one connection open at a time. When you operate in wireless mode, the RS-232 connection acts as a monitor/logger. It will give you an opportunity to quit TCP/IP mode by pressing any key within the first five seconds, in case wireless doesn't work (basically, you can't lock the keys in the car, because you can always recover via RS-232). 3. Wireless on your network You might like to use the device wirelessly OR via RS-232. If you want this connected to your own network, enter the SSID and password for your wireless system (note, it is impossible to connect to an "open" system, and the password NEEDS to be 8+ characters). You MIGHT want to "lockdown" TCP/IP if you are not the only user, and you might want to restrict use to 5 minutes of inactivity if you are demonstrating this to other people with the TCP/IP timeout. When you switch to Client mode and reboot to TCP/IP, the RS-232 connection acts as a monitor/logger. For client mode, it will attempt for 15 seconds to connect to your network. If it cannot (wrong password? Case?) it will revert to Access Point mode. It will give you an opportunity to quit TCP/IP mode by pressing any key within the first five seconds, in case wireless doesn't work. (basically, you can't lock the keys in the car, because you can always recover via RS-232). Note that unit will appear in your router wireless list as i8080-XXXX, with XXXX derived from your supposedly unique chip ID. The IP address that your system has assigned to the unit is also printed on the RS-232 console. Robustness/Bugs 1. The TTY delay may or may not always work. 2. Abrupt wireless disconnects (as opposed to a Telnet disconnect) may hang up TCP/IP connections. 3. NEVER reboot/power off the unit while a disk drive light is on or while things are being saved to flash. 4. No doubt, others. Future Plans: I may try again to port this to the ESP32. The toolset (for spiffs, etc) is not exactly complete/robust yet, but the entire thing should be able to fit into one package with no SPI RAM. It should also be faster, perhaps fast enough to emulate a Z80. Security Basically, this entire design (especially my part) is TERRIBLY insecure and was not written to exist in a hostile environment. It should NEVER, NEVER be allowed to hang on the Internet directly (through a wireless router with a firewall and NAT, or via a VPN, OK). Much of the secuirty that there is is physical - sensitive operations are accomplished only via RS-232 and probably in close proximity to the owner (particularly in "lockdown" mode). The FTP and OTA modes are transient modes and should never be left in those modes after they are used. The code itself stores SSID's and PASSWORDS in CLEAR TEXT in the SETTINGS file in ESP8266 flash memory; therefore, physical security of a programmed and configured unit is a MUST.