View source for ESP8266-01

A Wi-Fi module and Real Time Clock (RTC) were optional additions to the full cased Spectrum Next at the time of the original Kickstarter. They can be added to development boards and units that don't already have them. Although the RTC requires soldering components to the board, but the Wi-Fi module is a push-fit component.

== Hardware Requirements ==

Adding Wi-Fi to a board requires only a ESP8266 ESP-01 module. This supports 802.11 b/g/n at 2.5 Ghz including the WPA and WPA2 security protocols. The mounting point for the module is just behind the VGA port.

ESP modules have an updatable firmware although updating them isn't always practical depending on the specific device constraints.  In general the standard firmware, should work out of the box with the Spectrum Next. If you're buying a module, check it has a standard "AT" firmware.

The Wi-Fi makes use of the on-board UART (Universal Asynchronous Receiver-Transmitter) of the Spectrum Next (you can use this without a WiFi module for serial connections as as well.) The UART on the Next board (built inside the FPGA logic) can control the RX/TX lines from 2400 bps up to 115200 bps (the default speed). The ESP module uses the "AT instruction set" of a typical modem and the latest PDF is available here: https://www.espressif.com/sites/default/files/documentation/4a-esp8266_at_instruction_set_en.pdf although this is rarely found in any deployed ESP01s in the KS1 line of Next's.

Other versions include:
* v0.30 https://specnext.dev/esp8266_at_instruction_set_en_v0-30_0/
* v1.3 https://specnext.dev/esp8266_at_instruction_set_en_v1-3_0/
* v1.5.4 https://specnext.dev/esp8266_at_instruction_set_en_v1-5-4_0/
* v2.2.1r1 https://specnext.dev/esp8266_at_instruction_set_en_v2-2-1_1/
* v3.0.3 https://specnext.dev/esp8266_at_instruction_set_en_v3-0-3/

Anecdotally, Version 1.x seems the most common on independenly purchased modules from Amazon and eBay across a sample size of approximately 50 devices.

== Software Support ==

This information relates to [https://www.specnext.com/latestdistro/ TBBlue SD Distribution] 2.00.26 and later (2019-01-27).

The distribution contains dot commands (including "UART") and the "TERMINALS.BAS" program for working with the Wi-Fi module.

.UART is a simple DOT command that works in NextZXOS (and ESXDOS) to allow you to talk to a connected device which could be a Wi-Fi module.  Due to the limitations of the 512 byte hardware buffer ,it can only be used for small amounts of data and is mainly intended to allow diagnosis. It does include a simple CIPSEND mode that allows connections to be made with an ESP Wi-Fi module.

UART.DRV is an interrupt driven driver (NextZXOS only) which can provide a 16K software buffer which means much less incoming data is lost.  There is both a simple demo IUDEMO and a terminal program (not a DOT command) that provides an alternative to .UART that can handle much more data.  This is intended for users of the port without the Wi-Fi module really but can be used to setup the ESP.

The TERMINAL.BAS program is much better than .UART and you will have better results following through some of the examples below.

You can also begin to play with the real feature of the Internet Toolbox which is the ESPAT driver for BASIC (again NextZXOS only). It can be used with the BASIC ESPTERM program to chat over an IP link and the ESPHTTP sample program shows how a web page can be retrieved from BASIC (but not rendered.)

The Source code to the IRQ stub is provided to allow the ESPAT code to be used in games that take over the machine, providing a gaming API.

Be sure to check out NXTel the Viewdata (Prestel/Teletext) terminal that allows the Next to connect and get news pages from Viewdata servers already online.

=== .UART ===

'''Key mapping'''

{|
|-
| Spectrum key		|| PS/2 Key 	|| Action 
|-
| EDIT		|| SHIFT+1 	|| Cycle output mode 
|-
| CAPS LOCK	|| SHIFT+2 	|| On/off toggle (on by default)
|-
| TRUE VIDEO	|| SHIFT+3 	|| Debug mode for CIPSEND on/off (silent)
|-
| INV VIDEO	|| SHIFT+4 	|| CIPSEND mode on/off, also does an ATE0
|-
| GRAPHICS	|| SHIFT+9 	|| Change BAUD rate 
|-
| DELETE	|| SHIFT+0	|| Delete 
|-
| SYMBOL SHIFT + SPACE ||  CONTROL+SPACE  || Exit Program
|}

== Basic Connection ==

Run the .UART command, or better LOAD "TERMINAL.BAS" and RUN it.

First of all when you press ''ENTER'' you should get 'ERROR' because you didn't send a valid command to the ESP module. If you don't then it may be a number of things:

* You are using the TBU and firmware BEFORE 0.8 and NextOS 1.92 - if so this will only work at 3.5Mhz so slow the machine down and restart .UART.
* You are using a TBU and firmware with a Core .29 or greater, with an OLD copy of the .UART program which wrote the BAUD rate differently - if so when you cycle through the speeds (EDIT/SHIFT+1) you will find it may 'work' at 38400 - it is actually a fluke as the old value for that rate is quite close to the value needed for 115200 on the new system.
* Your module may have come with a default baud rate other than the 115200 of the Next. Using GRAPHICS (SHIFT+9) you can cycle through each option pressing ''ENTER'' until you see "ERROR!" (If you can physically see the module then many have a little blue light that flashes when receiving.)

If you believe the baud rate is set incorrectly on the module, from version 2.2e of .UART, there is a command to search all possible settings from about 4000 to 2.2M baud:

 .UART -f

Once you have the module reporting 'ERROR' you should be able to type 'AT' and press ''ENTER''. That should give "OK".

Probably the first thing you want to do is tell the module to use the default speed of the next so type:

 AT+UART=115200,8,1,0,0 

and press ''ENTER''.

You now need to use ''GRAPHICS'' (SHIFT+9) to go back around to 115200 so that ''ENTER'' gives ERROR and AT ''ENTER'' gives OK again....

We just used one of the AT commands:

 AT+UART=<baudrate>,<databits>,<stopbits>,<parity>,<flow control>

== Getting on the Network ==

Now to connect to a Wi-Fi access point:

First let's check that the system is in STAtion mode:

 AT+CWMODE=?  

This will give 1,2 or 3 (where STA=1, AP=2, Both=3). Mode 1 or 3 is fine but, more config is needed in mode 2.

Set the mode:

 AT+CWMODE=1

List Access Points:
 AT+CWLAP

To join an Access Point:
 AT+CWJAP="wifinetwork","password"

Note that the module will retain the Wi-Fi connection and you can just do an AT+RST which will reset the module and give a CONNECTED and GOT IP.

Here are some more common AT commands:

{|
|-
| AT+CIFSR || Echo the current IP address on the network
|-
| AT+GMR || Echo the current versions of the software on your module
|-
| AT+CWQAP || Forget the WiFi network and password
|}


== Connecting to a Server == 

Let's try connecting to a server on the internet:

 AT+CIPSTART="TCP","www.google.com",80 

That is just the first stage and means there is now a pipe from the ESP to the Google server. Before it does anything you need to send it something. If you do feel brave before you close the connection then you can send:

 AT+CIPSEND=7

at the ">" prompt which appears you should type:

 GET / 

These 5 characters need to be followed by a character 13-Carriage Return and a 10-linefeed. I.E. Just press return twice.

AT+CIPSEND=length allows you to get the ">" prompt and type 'length' characters. Incoming replies will be "+ IPD,length:" followed by the data (no space). Finally you will need to close down the connection:

 AT+CIPCLOSE

This is very fiddly so .UART and TERMINAL include a mode called CIPSEND that does all the decoding for you.

If you press INV VIDEO (SHIFT+4) then the system will send an ATE0 to stop the ESP echoing everything and then anything you type will be sent followed by a Return and Newline.

You can also on TERMINAL use EDIT (SHIFT+1) to go into immediate mode, where everything you type is sent as you do it. In this mode to send a LF you need to Symbol Shift + ENTER after pressing ENTER (or SHIFT and 6 / down-arrow) to send a  10 / LF / Newline.  This makes AT commands more complex but this mode is more useful to use the program as a traditional text terminal.

Anything the other end replies with will just appear. Note that at 14MHz you will get more text before the system begins to lose data due to the delays in printing what is received. Far more works on TERMINAL than .UART.

This mode is good enough to be a simple text terminal for a shell on a linux box or any test system.

If you connect to Google again and use CIPSEND mode then send four lines EXACTLY like this:

 GET / HTTP/1.1\r\n
 Host: www.google.com\r\n
 Connection: close\r\n
 \r\n

(where the \r\n represent what CIPSEND will do when you press ENTER)

Your screen will fill with the RAW data that makes up the very simple Google home page...

In order to get back to talking to the ESP you will now need to exit CIPSEND mode by pressing INV VIDEO (SHIFT+4) again.

== Connecting to a Non-HTTP Server ==

 AT+CIPSTART="TCP","dict.org",2628

Should get you:

220 ..............some WELCOME.....

Go into CIPSEND mode with INV. VIDEO (SHIFT+4) and type:

 DEFINE wn server\r\n

And you should get:

 150 1 definitions retrieved
 151 "server" wn "WordNet (r) 2.0"
 server
     n 1: a person whose occupation is to serve at table (as in a
          restaurant) [syn: {waiter}]
     2: (court games) the player who serves to start a point
     3: (computer science) a computer that provides client stations
        with access to files and printers as shared resources to a
        computer network [syn: {host}]
     4: utensil used in serving food or drink
 .
 250 ok [d/m/c = 1/0/18; 0.000r 0.000u 0.000s]

Now send:

 QUIT

and you will get

 221 bye [d/m/c = 0/0/0; 16.000r 0.000u 0.000s]


== Other Hardware ==

In addition to controlling the ESP-01 Wi-Fi module, the .UART command also provides facilities to use the serial connection port, either directly through some form of serial converter (e.g. a USB to TTL serial) or standard RS232 module (probably based on the MAX232). 

A USB serial connection allows you to do all sorts of clever things - it is possible to connect up to a PC like this for transferring data.  In fact if you were an early purchaser you probably bought one with your ESP-01 as it is the one needed to program it. 

If you use one of the easy to get TTL modules then you can communicate with PC's and other older machines - E.g. a real Spectrum with Interface 1... KevB is using one for his PC - see article on the forum at https://www.specnext.com/forum/viewtopic.php?f=6&t=895  

It should be possible just to hook up to an external Raspberry PI for example and use a serial console connection allowing you to use the ZX Next as the keyboard... as the voltages match it should be fine just to connect the UART RX/TX and GND to the PI's PIN's 4/5/6 GND/TXD0-GPIO14/RXD0-GPIO15. See https://elinux.org/RPi_Serial_Connection

There is a diagram of the GPIO header here: https://elinux.org/RPi_Low-level_peripherals

Be aware of the differences with a Pi 3.


== Further Reading ==

For further information, see [https://www.specnext.com/the-next-on-the-network/ "The Next on the Network" at SpecNext.com] and in the TBBlue Distribution the file "\docs\extra-hw\wifi\WIFIand UARTReadME1st.txt"