ESP8266-01

From SpecNext official Wiki
Jump to: navigation, search

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 past 115200 bps (the default speed) all the way to 2Mpbs. 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 note-worthy versions include:

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 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]

Crash diagnostics

If the ESP-8266-01 reboots for any reason it will report a "rst cause: " with one of the following numbers.

    0: Normal power on reset
    1: Hardware watchdog - kernel hung
    2: Software watchdog - uncaught exception
    3: Software watchdog - watchdog hung, kernel called "system_reset"
    4: Software restart
    5: ESP woke from deep sleep

Further Reading

For further information, see "The Next on the Network" at SpecNext.com and in the TBBlue Distribution the file "\docs\extra-hw\wifi\WIFIand UARTReadME1st.txt"