• Firmware
  • User Script
  • Hardware
  • Wifi Browser
  • Computer Serial Port
  • Computer Software
  • Communications
  • Memory
  • My Preferred ESP modules
  • Hardware Tips
  • Buying Tips

CiccioCB’s Annex Wi-Fi BASIC is a BASIC interpreter designed to run on the ESP-8266 family of wifi ‘System On a Chip’ (SOC) devices.

The ESP-8266 family of devices are smaller than an arduino, but run faster and have more available program memory, plus have integrated wifi.
Real-time wifi editing of interpreted BASIC is much quicker and easier than recompiling and uploading every slight edit using arduino environment.
No compiling is needed, you could Copy and Paste an entire new BASIC program then Save and Run it quicker than you can read this sentence.
The BASIC programming language is one of the easiest to learn and use because it is based on human-readable English language.
Don’t let names fool you though, because BASIC does not mean simplistic, and this version of ‘basic’ from Ciccio (pronounced “Chitch” “eee” “ohh“) is much more than just a Basic interpreter… it is a complete integrated BASIC development ‘system’, with amazing features and capabilities.

Includes: Full feature set available to both 1Mb and 4Mb devices. Separated Firmware and SPIFFS management, allows firmware updates without data loss, and zip data backups and restores. Integral SPIFFS repair facility (never loses files to corruption). IMMEDIATE window to execute specified instructions and evaluate expressions even when the script is not running. Script COMMAND instruction able to evaluate anything similar to Immediate window. F2 invokes context-sensitive Online Help of Basic keyword at flashing cursor in Editor. Full Error control.
Too many other excellent features to mention + more software instructions than you will know what to do with + all sorts of hardware devices.
 

System Components

 
   Firmware
The essential heart of the system is the Annex Wi-Fi interpreter firmware, which is a ‘binary’ file that runs on the ESP device processor.
 

   User Script
An ascii text file containing a list of ‘human-readable’ instructions which Annex Wi-Fi interprets and acts on as it parses through it.

   Hardware
The firmware runs on ‘portable’ ESP-8266 wifi devices which can be considered as remote ‘Satellites’ – there may be many, in different locations.

(See some ESP modules and hardware tips further down this page)

   Wifi Browser
Communications with the remote ESP satellites devices is done via wifi (radio) using a web browser on computer or smart-phone etc.
 
   Computer Serial Port
Launching (flashing) of the ESP satellites is by a computer-based ‘ground-control’ program called AnnexToolKit.exe which uses a Serial Flasher ‘umbilical cord’ to upload the binary firmware image to the ESP device.
 
   Computer Software
In addition to a Serial Flasher, the Annex ToolKit utility contains a Serial Monitor console, a UDP (network) Control console, a Backup and Restore facility, an HTML Converter utility, an OTA (Over The AirUpdate Server, and a File Manager utility for Upload and Download of files between computer and ESP device(s) – the usage of all features will be explained in due course.
 
   Communications
After an ESP satellite has been ‘launched’ (flashed) by serial port, it ‘serves up’ some in-built web pages which allow it to be connected to remotely by browser over wifi. The served pages provide a remote script editor and debugger, plus remote OTA firmware updates, thus making the comprehensive ‘ground-control’ computer support ‘tool’ and serial ‘umbilical cord’ no longer essential for continued operation.
 
Web-browser connection to the remote ESP satellite modules can be done using any terminal with wifi browser capability, ie: desktop computer, laptop, tablet, smart phone, etc… and appropriate Internet access can (if wished) offer connection from anywhere in the world.
 
Alternatively, Annex WI-Fi Basic devices can be configured to auto-run a script at power-on to provide isolated autonomous operation.
 
   Memory
Annex WI-Fi Basic runs on any of the ESP-8266 family of wifi devices which have 1Mb or more of memory (cannot be used on 512Kb devices).
The firmware fits into 1Mb of device memory space while leaving sufficient memory remaining for the required SPIFFS file system to hold data.
The SPIFFS filing system permits storing files on available device ‘flash‘ memory – but note that it has some restrictions:
    31 maximum filename characters – including folder names and ‘/‘ ‘.‘ separators.
Case-sensitive, eg: /program/file.bas is a different file to /Program/file.bas or /program/File.bas or /program/file.BAS etc.
    Dynamic file allocations to optimise flash memory usage (flash cells have a max number of writes limitation before memory failure).
 
Devices with more than 1Mb memory have the same size firmware file, but can have larger SPIFFS for increased file storage.
During flashing, Annex WI-Fi Basic will auto-size its empty SPIFFS according to available device memory (currently from 1Mb to 4Mb).
When uploading files using the File Manager, the SPIFFS filing system allocates them into memory according to a dynamic algorithm.
 
binary backup of the firmware and/or SPIFFS data is a ‘snapshot‘ of configured dynamic flash memory, thus making it size-dependent.
IMPORTANT NOTE: Because of the size-dependent memory allocations, binary backup images give potential for 2 problem scenarios:

   1. Restoring a binary image from a larger memory device onto a device with less memory will cause SPIFFS corruption.

   2. Restoring a binary image from a smaller device onto a device with more memory will not allow the additional memory to be used.
Uploading individual files (or groups of files) using the SPIFFS file system allows it to dynamically allocate them according to available memory.

It also permits copying just those required files, rather than the full SPIFFS image size even if empty of contents.

 

The Annex Toolkit File Manager tool now includes ability to upload selected files from zip, and similarly to download selected files to a chosen zip.

This offers ability to load and save projects to specific project zips, ideal for sharing projects, or as transparent browsable backups.
   My Preferred ESP modules

This is not intended as a comprehensive hardware device review,
just a mention of some of the hardware I find useful, and why.

Top of my list is the Serial Dev Kit ESP-202 module – thankfully I bought several while they were plentiful, because they are now harder to find.

Some of the useful features are:

On/Off switch … sounds obvious, but I don’t know of any others with one.
Easily accessible GPIO0 jumper … offering push-on switch replacement.
RGB LED
 connected to gpio’s 12, 15, 13.

Onboard status LEDs for gpio’s 16, 14, 2, 0, 4, 5 and power.

The RGB LED and onboard status LEDs allow easy monitoring of gpio pins without requiring external LEDS and limiting resistors.
Top-mounted breakout pins.
On-board USB UART
 … my normal method of powering the module, even when portable from a USB solar power bank.

Onboard switchable ESP-01 socket … allows plugging in ESP-01’s for testing, programming, flashing.
Battery box supplied … but instead of soldering it directly to the module, I solder pins to the module and connect dupont female sockets to the box.

This allows the battery box to be plugged on if needed, or to plug on a rechargeable Lipo instead, or it gives

a 5v pin available from the USB to power external 5v devices.

NOTE: Even though the ESP8266 is a 3.3v device its pins are 5v tolerant and I regularly power 5v modules from the 5v battery pin and connect the modules 5v logic output directly to an ESP pin, always without problems.
All usable ESP pins are broken out, offering 5v & 3.3v pins plus 3 GNDs

 
Replacing the gpio0 jumper with a plug-on momentary pushbutton makes it more convenient for one-handed operation with the On/Off switch to boot up the device into flashing mode.
It also offers a handy method for quickly plugging on different switches and sensors for trying with projects.

Second favourite is a “Next Evo” produced by TrackerJ,
It has the autoflash feature similar to NodeMCU but it is slimmer and therefore more breadboard friendly.
Plus the pin holes are left vacant, so it can be fitted with long pin header sockets if wished.
Some carefully applied strength can widen the long pins sufficient to fit Wemos D1 Mini shield footprint.

But… what makes this module really useful for me, is the provision for fitting an i2c header socket.
Look at the bottom one shown in the picture and you can see a PCF8591 AD/DA module plugged in and standing up vertically – giving 4 analog inputs (connected to a trimpot, LDR & thermistor) plus a digital to analog converter… and all without any wires. This offers the easiest way for i2c development that I know of.

I bought a couple via email, and when I mentioned the difficulty of finding or ordering them online TrackerJ said that his sales are normally from ‘walk-in’ customers… so I don’t know if they will be available online.

Another useful dev ‘special’ is a single-inline module bought from a Greek ebay seller a couple of years ago.
It plugs upright into a breadboard, giving a very narrow footprint, allowing more room for other components.

You can see one resting on the breadboard, and another plugged in above it with components on either side.

All the normal pins are available in a single row for plugging into a breadboard or female header socket.
The UART connections are separate and opposite.

The guy making them was also advertising them elsewhere, so they may still show up in an online search.

I’m not a fan of the relatively chunky NodeMCU, but the version with integral OLED offers a handy self-contained on-screen display for output.

The Wemos D1 Mini is the NodeMCU baby brother with a more practical footprint and offering a range of plug-on shields, even an OLED display.

Of particular note is the dual (and triple) base adapter which allows plugging in additional shields… because it also offers great potential for using 2 devices side by side – perhaps as a serial bridge between Annex and Arduino, or to bridge an isolated secure subnet to an internet subnet.
 

A nice feature of NodeMCU and Wemos devices is their easy ‘autoflash’ capability which avoids having to ground gpio0 during reset for flashing.
In practice that’s not so important because even 1M Annex WI-Fi Basic devices only need flashing the first time, then can be updated by OTA.
Just remember than an OTA flash is not an update, it is a new firmware flash which will overwrite existing data. so take a zip data backup first.
 

Of the other ESP modules I’ve tried, most don’t get used much because they don’t offer a useful advantage.

But perhaps special mention should go to the Wemos D1 arduino look-alike, for its familiar footprint.

Handy for use with arduino prototshields etc, and of course LEDs and jumper wires can plug straight in.

Can be powered by USB, and has simple ‘autoflash’ facility, so offers a useful experimenting platform.

What I DO use a lot of – and deserves special mention – is the wide range of Sonoff/Itead ESP-based products, which are convenient, practical, affordable… and in most cases, usable as-is. If you need to control something using a relay, there is a neat ready-made Sonoff that could do it.

 
 
 

   Hardware Tips

You’ll probably want a breadboard – and be aware that if the thin red and blue lines don’t run unbroken full length it is because they are denoting a track break, so applying power to one end of the breadboard won’t power the other end unless the supply rail gaps are bridged with jumpers.
You’ll probably get a pack of assorted length male2male jumper cables, but you may also want 30cm male2male, male2female, female2female.
I cut up and join some jumper wires to make a variety of male/female dupont “Y” adapters to allow more than 1 connection to a single pin or skt.
I also do something similar with a couple of 4.7K resistors to make a 3-legged i2c pullup assembly with a common +V connection.

Typical ‘tactile’ momentary push-buttons have a tendency to pop out of breadboards, so I usually connect to a multi-switch module (not a matrix).

While your soldering iron is hot…LEDs are quicker and more convenient to use with an appropriate current limiting resistor already attached.

(use an LDR instead of a resistor to give automatic brightness level adjustment)

I have some breadboard-friendly 6 LED modules (can’t understand why they didn’t do 8 LEDs) with integral 1K limiting resistors.
But it is worth pointing out that if for instance I wished to display individual switch status leds for all inputs of an 8 port expander it would either require 8 gpio outputs to have one for each of the leds, or require a second 8 port expander configured specifically as outputs for the leds.

A more practical alternative could be to use a single gpio pin to address as many neo-pixels as I could realistically need (potentially hundreds).

I plan to do a chapter on neo-pixels later, but suffice to say now that a neo-pixel is basically a clever RGB LED plus driver chip with a digital input, plus a digital output for optionally feeding into a following neo-pixel.
Each neo-pixel takes the ‘address’ of its position in the chain, and each is capable of being controlled independently by sending an RGB colour code to its address (or all the chain can be addressed at once).

Neo-pixels are available as single pixels, or in a hard stick of 8, or rings of 8, 12, 16, 24 etc, or wired into strings, or as flexible ‘tapes’ of 1m or more, or 8×8 or 16×32 matrix grids etc… and the digital output of any neo-pixel can be chained into the digital input of any other, irrespective of their styles.
Each and every neo-pixel is individually addressable, and their RGB colour values are all individually controllable between 0 (off) to 255 (full on).

So in the case of the example 8 switch port expander, an 8 neo stick could allow displaying the status of all ports in any chosen colours… using 1 gpio.

Breadboard power supplies have a USB power input, as do all the ESP devices with onboard USB UARTS, and various other types of modules.

But you’ll probably want to reserve your computer USB port for flashing and serial data, so you may want to buy a few cheap USB chargers – you can buy household mains and car lighter versions for less than a quid.

A USB power bank can be a handy device for powering mobile projects on-the-go.

Some have solar panels for charging during the daytime without needing a mains supply.

Housing one inside an inverted transparent plastic kitchen box with water-tight clip-on lid
is handy for powering external projects such as an ESP with radar detector for instance.
 

Search for Solar Power Bank and you should find some for less than £4 (free postage).

 

   Buying Tips
All these sorts of items are available off ebay with free delivery on a slow boat from China for less than it costs to drive to your local supermarket.

If you select “Buy it now” Format then wait for screen refresh, then select “Worldwide” Item Location and wait for refresh, then tick “Free postage” Delivery Option, you will be presented with new items available for sale to other countries at perhaps better exchange rates still with free delivery.
if you enter .99 for example into the Price “to” window then click the “>>” button it will only list any items costing less than a quid.

If a cheap free delivery item is available for about the same price from several sellers, and is cheap enough that I decide to get more than one of them, I have learned not to put all my eggs in the same basket by ordering multiple items from the same seller… if it is free delivery then it doesn’t cost me any more to order only 1 from several different sellers, then if there is a problem with any one item, it won’t affect any of the others.

Similarly I have learned not to order many items at a time from a seller – it doesn’t benefit me if a seller bundles many free delivery items into one bigger package, but it will be worse for me if there is a problem with a bigger package of many items, so I spread them out to be sent individually.

Be aware that there is a growing number of cheating scammers who deliberately undercut prices to grab the cash flow without any intention to supply. You could be waiting several weeks for a delivery that never comes, then eventually be forced to seek re-imbursement from ebay.
But you can usually spot such scammers simply by looking at their total transactions… I would rather pay the going rate to a seller with a rating of tens of thousands rather than risk being conned by a deliberate scammer with a rating of less than 2000 because of trying to save a few pennies.
So if you’ve had good dealings with a seller, go back to him knowing he’s genuine, rather than risk penny-pinching to slightly cheaper unknowns.

Occasionally some items don’t work, occasionally some don’t arrive, but the paypal money back guarantee means you never need to lose out.

Most ebay sellers are very protective of their feedback reputation, so will attempt to keep you satisfied without you needing to complain to ebay.

If you do need to escalate a problem to ebay you have a realistic expectation of receiving satisfaction, which is more than you may get elsewhere.

Ali express does not impose an ‘honesty’ feedback system on their sellers, and has more financial incentive to favour their sellers rather than the victims, therefore dishonest sellers with no reputation to protect and little fear of reprisal can (and some do) openly lie and cheat to ‘rip off’ buyers knowing there is nothing their victims can do about it. So don’t be tempted by prices that are too good to be true, because they may cost you dear.

Wherever you buy from, any ripoff scammer who is deliberately baiting a honey trap can obviously under-cut the best prices of all genuine sellers.

  • But when all is said and done, it is astonishing what cheap hi-tech devices and modules we can buy sent free delivery from around the world.
  • Serial Flasher Overview
  • Firmware Flashing
  • First Contact

NOTE: The Annex Wi-Fi Basic package is completely portable and requires no installation… it can be copied, moved, or removed at any time.

Unzip the distribution package to a folder of your choice, currently it has the 3 sub-folders listed below, but we will also add a zips folder later.

build” – this is where the .bin (binary) firmware files are located, and is where to copy any subsequent updates.
upload” – this is the default ‘departures lounge’ for files to be uploaded from computer to the ESP – it can be over-ridden when wished.
download” – this is the default ‘arrivals’ destination where selected files are saved to when downloaded from the ESP.

 

Run AnnexToolKit.exe from the unzipped parent folder, it includes:

Serial ‘Flasher’ utility
File Manager utility
OTA Update Server
Serial Port Monitor
Backup and Restore facilities
UDP Control Panel
HTML to BASIC Converter
Syntax Highlight utility
Assuming not blocked by firewall etc, the AnnexToolKit utility should start up showing the Serial Upload window tab (see above).

Hover the cursor over any of the components to pop up a Tooltip description of the component.

   Serial Flasher Overview
Serial ‘flashing’ involves using the esp_tool.exe utility behind the scenes to connect serially to the ESP device and carry out the chosen task.
In order for the ESP device to be ‘responsive’ to the esp_tool (rather than pre-occupied running its own firmware) it needs to be made ready.
ESP devices can be ‘manually’ made ready, ie: started up into flashing mode, by holding gpio0 to 0v while the device is rebooted or powered on.
NOTE:  Each separate esp_tool operation (ie: each clicked coloured button) requires another restart into flashing mode.
Some devices have an automatic ‘autoflash’ capability whereby the esp_tool can set gpio0 low while rebooting the device into flashing mode.

 Read Module Info  blue button is non destructive, although it still needs the ESP device to be in flashing mode to read it.

 Flash Firmware Only  green button is non-destructive to any existing data, but will update the existing firmware by overwriting it with the update.
 

 Flash Firmware + Data  yellow button is fully destructive by overwriting firmware and data, Data Size chooses either Min data or Full distribution.

 Erase the Flash Memory  big red atomic bomb button is fully destructive and wipes out all firmware and data plus anything else within reach.
NOTE: A unique option of CiccioCB’s Annex WI-Fi Basic is that both the firmware and the SPIFFS data areas can be managed separately.
This permits updating of Annex WI-Fi Basic ‘Firmware Only using the green button without overwriting the users SPIFFS data files.
So in practice, users might only need to write a new SPIFFS containing clean ‘distribution’ data for the first ‘virgin’ install, and do updates after.

Module Type” contains a list of a few common type of modules, one of which will probably be suitable for yours.

Tick the ‘Advanced Options’ checkbox if you wish to display the selected modules parameters in the orange Advanced window.

Serial Port is your UART (FTDI) com port – it only shows as available if it is actually available.
If you are not sure of your devices COM port, check what Toolkit ports are displayed without your device plugged in, then plug the device in and restart the Toolkit, then check to see what new COM port is now available.

Speed is the baud rate setting for your devices UART (FTDI).
If confident of your selected device and parameters, try flashing at the fastest speed, then drop to a slower speed if the flashing fails.
If not confident of settings, 115200 is a good solid speed that won’t take forever.

Module Size is the amount of flash memory the device has. Currently only 1Mb to 4Mb is supported (greater than 4Mb can be flashed as 4Mb).

The Basic firmware sits in 1Mb leaving some memory still available for SPIFFS to store uploaded data files.

Devices with more than 1Mb have the same size firmware, but can have larger SPIFFS for increased file storage capacity.
 

Don’t worry if some of the above terminology is unfamiliar, it is just an overview, so now let’s draw a line under it and move on at an easy pace.

 —————————

 

 

First time ?
Unsure about something ?
Don’t know your device details ?

Don’t worry
… you can’t go wrong and will soon gain confidence when you follow these next few simple steps:

  Firstly, understand that the blue ‘Read Module Info‘ button will just harmlessly read info from your device (you cannot do it any damage).
Secondly, understand that if you can read the device memory size, you will also already have discovered all other required device parameters.
Thirdly, after retrieving your device memory size, you will already have proved the device can be accessed for flashing with firmware.

So we just need to systematically take whatever steps are needed to ‘Read Module Info‘.

It may be as simple as just clicking the blue ‘Read Module Info‘ button if the device has ‘autoflash‘ capability, such as NodeMCU and Wemos and many others. Try it and see.
But if not, set Module Type to “Generic module“, set Speed to 115200, then reboot or power-on the module with gpio0 shorted to 0v.

Now try the blue button again, and hopefully that should do it.
If not, try other Module Types and keep trying the blue button until something works.
If necessary, try rebooting your device with gpio0 shorted to 0v again, then restarting the Toolkit again, just to make sure. And make sure the device UART is connected properly.
If you’ve ever flashed that device before, you should already know how to put it into flashing mode… and that’s all you are trying to do – then click the blue button.

You are looking for the blue buttons popup info window, as shown here on the right.

You may notice that I had ticked Advance Options to also display the orange details area.
Pay attention to the old Advanced values showing in the orange area, and notice that the popup window is showing it has discovered new values.
After you OK the popup info window, the newly discovered device parameters will get updated in the orange details area… how easy is that.
And of course the discovered memory size will also be updated in Module Size. So now you have all the information needed to flash your device.
But you don’t even need to know the details yourself, because when it is accessed by the blue button the details are automatically discovered.

Which means you could do exactly the same thing again, but instead of the blue button, use the green or yellow to install firmware to the device.

NOTE: Annex WI-Fi Basic requires some minimum essential support files to be available on SPIFFS before browser connection is possible.
So if you flash green ‘Firmware Update Only’ to a virgin device (or after using the BIG RED BUTTON) you will have an empty SPIFFS with no files, and will need to upload any required files manually using the File Manager tab in AnnexToolKit… eg: “edit_area_full.js.gz” is required by the editor. 

So it is more convenient to use the yellow Firmware + Data button to do a first-time install… if you want all the distribution demos and examples select ‘Data Size’ “Full“, or else select ‘Data Size’ “Min” if you want to leave your newly flashed device uncluttered with only the minimum files.

Use the green Firmware Only (Update) button when you already have existing data on the device (it is prudent to backup your data to zip first).
   FIRMWARE FLASHING
Ensure your device has an appropriate UART connection to the computer (this is specific to your ESP device and computer serial port).
Select your UARTs com port.
Select Speed (baud rate).
TIP: Some devices (including Wemos D1 Mini and NodeMCU) work ok on the fastest speed setting, so fastest is worth trying first.
Some ESP modules such as Wemos and NodeMCU are capable of being autoflashed (automatically re-booted into Flashing mode), otherwise you will need to manually boot your device into flash mode by ‘shorting’ the gpio00 pin to 0v (if no flashing button) during power-on or reboot.
 
NOTE: The AnnexToolKit utility contains its own Serial Monitor which is designed to share the com port with the Serial Flasher utility.
After flashing, the ESP device will automatically quickly reboot into Basic which will report its settings to the serial port, and if the Annex WI-Fi Basic serial monitor has already been connected prior to flashing it will grab the com port after flashing is completed to show the bootup report.
You can use a different Serial Monitor program if you prefer, but not while flashing, else it may grab the serial port and cause the Flash to fail.
Click the bottom right Serial Monitor button to open its window, confirm correct com port, then click Connect… the button should turn green.
Slide the Serial Monitor window clear of the Log window so you can read log messages as well as view the serial monitor report…
Click the required green Firmware Update or yellow full Firmware plus Data button – the Flashing progress will be shown in the Log window.
Note that if yellow button is used, the log window will first show the firmware progress, then followed by the SPIFFS data progress.
A confirmation window will pop up after successful completion, and you should see Annex WI-Fi Basic boot into AP mode in the Serial Monitor.
 
 

   FIRST CONTACT

A fresh install of Annex WI-Fi Basic will cause the ESP to boot with an SSID and AP (Access Point) name starting with ESP (+MAC address).
Connect your computer wifi to the newly available ESP SSID showing in the computers wifi list.
TIP: Choose the ‘Connect automatically’ option to avoid having to manually reconnect each time the ESP device is rebooted.
 
When wifi is connected, open a new browser tab and enter the default IP address 192.168.4.1 into the address bar then press Enter.
A default Output page will open, which is where users would connect to if auto-running the default.bas script at bootup to display web content.
 
Right-click on the Editor button and open the Editor in a new tab – this opens your dev ‘GUI’ where all your script development is done.
TIP: Shuffle the horse in front of the cart if you prefer, by dragging the newly opened Editor tab to the left of the Output tab (or vice versa).

TIP: If your browser is not maximised, you can drag and drop the Output tab off the browser window, then adjust the 2 separated windows to both be visible together side by side. This would allow you to edit and run your script from the Editor page while viewing the results in the Output page at the same time, without needing to keep switching between tabs.

 

That’s it!
You are now in control.

 
We’ll get around to explaining the controls in a while, but the best way to learn is by hands-on, so just dive straight in for now and try everything – you can even try to mess things up if you like, and play around with the actual demo examples, cos one of the coming chapters will explain how to use the ‘Big Red Button’ to make a quick clean new start if ever needed.

To load a script into the editor, click the Open button, then double-click the selected .bas file (check out the examples in the “/program” subfolder).

 

TIP:  Use the Online Help
Pressing F2 while in the Editor will open an Online Help page, and jump to the syntax entry for whatever instruction the cursor is sitting over.
The significance of that is worth repeating – hover your cursor over any Annex script instruction then press F2 for context-sensitive help.
Obviously the availability of Online Help in the Editor is dependent on the computer having an internet connection at the same time as a wifi connection to the device.

On my computer I use an RJ45 network cable interface for internet and intranet, and an isolated wifi router just for connecting to the ESP devices, so even when connecting to the default IP address of 192.168.4.1 the computer browser still has internet access for the online help.

If your computer only has a single wifi network connection, your device can be configured to pick up a DHCP IP address from your wifi route, which you can then connect to in the browser Edit page as well as having internet access via your wifi router – note that the allocated DHCP address will be shown in the serial port monitor at device startup..

If you wish to see all related Help entries about something, eg: Neo pixels, enter neo in the search, then simply check out the results.
Read the scripts comments (which show up as green lines starting with a single-quote character  ).
Look to see where the script output is being sent:
PRINT sends output to serial port (your serial monitor should still be connected since flashing, else open it again)
WLOG sends output to the log window of the Editor web page
HTML ‘serves’ to the Output web page (the first page that was opened)
Click the Run button to execute the script, then check it’s output to see if it did what you expected (we learn by our experiences).
Basically, that’s all programming is… creating a sequence of script instructions that will eventually run as expected!
I say “eventually” because usually (for me, anyway) there are many mis-spellings and mis-understandings which I need to ‘debug’ first.

 

Below are some videos showing how quick and simple it is to flash Annex firmware, but it may help to know about the different scenarios, and what may be most appropriate for you.. .

Various ESP-8266 devices are used to demonstrate different methods of flashing for different types of devices, so even if yours is not identical, its method should be similar to one shown here.

Getting Annex up and running is basically a 2 step process…
   1.  Initially ‘flash’ Annex firmware to an ESP-8266 device using a serial ‘com port’ connection
   2.  Thereafter connect to the device using wifi

Step 1 involves flashing the Annex firmware plus any data of your choosing to your ESP-8266 device.
The Toolkit utility contains the serial flasher, which has 4 coloured buttons to provide the different functionality.

The blue button is completely safe and merely reads the device parameters, although it must still be put into ‘flashing mode’ to accomplish it.
Only the green and yellow buttons actually flash firmware to the device.
The green button is not destructive to data, it only installs the Annex firmware without affecting any existing data.
The yellow button is ‘destructive’ because it installs the Annex firmware plus overwrites all existing data with the selected data package of examples – the ‘full’ data package needs a 4Mb device, whereas the ‘Min‘ package fits onto 1Mb.
The red button is completely destructive because it erases all contents – it can be used as a last resort prior to re-flashing if experiencing problems.
The red button can also be used prior to flashing ‘firmware only’ with the green button to ensure a clean new virgin start without any pre-existing clutter.

The use of any coloured button requires that the device is put into ‘flashing mode’ for that task.
Most devices with onboard USB (eg: Wemos, NodeMCU, etc) can be ‘autoflashed’ without manual intervention, buy there are exceptions (eg: Yison-202 Ser Dev Kit module).
The easiest way to find out is simply try to use the blue button… if it is successful then the device has ‘autoflash’ capability.

If not, then the device will require manually booting into flashing mode by connecting its gpio0 pin to to 0v while it is restarted.
(note: after booting into flashing mode, gpio0 no longer needs to remain grounded for the duration of flashing).

Step 2 – Connecting to the flashed device using wifi.
When the device is restarted after being flashed, it displays the MAC address and IP address in the serial console, and an SSID corresponding to the MAC address should become available in the Windows wifi list.
Connecting to that SSID causes the Windows wifi interface to assume an IP address on the same subnet as the ESP device.
This has a bearing on whether the F2 Online Help feature will be available from the Edit page on the device.
If the device is defaulted to 192.168.4.1 then the only way the Edit page address would have internet access is if the computer also has another bridged interface which has an internet connection (this could ensure that the device wifi subnet is normally isolated from internet access).

In most cases your computer will probably only have one network interface which is connected to your internet router, therefore any wifi devices which also require internet access (ie: for the Online Help facility) must also logon to the router.

This is why a connection dialog pops up when flashing with the yellow button (which overwrites all of the existing info and starts with an empty new ‘config‘ file).
It offers opportunity for entering router logon details to allow your new device to connect to your router and have internet access, otherwise the default IP address will be 192.168.4.1

(This can be done later by browsing to the default address and entering router logon details in the Config page, then noting in the serial monitor at reboot what address it has been assigned).

The device IP address can be connected to in the Toolkit utility File Manager tab for most management tasks.
Or it can be connected to in the browser for editing and running scripts.

 
 
  List of Serial Flashing Videos
 
 
 
 
 
 
 
  • Unzip the Annex WI-Fi Basic package to a folder of your choice.
  • Connect your ESP device to your computer serial Com Port.
  • Run AnnexToolKit.exe from the unzipped parent folder.
  • Select the appropriate Module Type, Com Port, and Speed (Baud Rate).
  • If your ESP device is not capable of ‘Auto-flash’ then start it into flashing mode manually (gpio0 to 0v at bootup).
  • Click the yellow ‘Flash Firmware + Data‘ button if doing a first-time flash, then follow the screen prompts.
  • After successful completion, the device will reboot and run the new firmware.
  • Connect wifi to the ESP SSID that will appear in the computers list of available Wifi SSIDs (takes a few seconds).
  • Browse to 192.168.4.1 to open the default Output window, then right-click the Editor button to open it in a new tab.
Enjoy
There are 2 different types of control console which are provided for different purposes…

1.  A computer executable program called AnnexToolkit.exe acts as a ground-based Mission Control for the remote ESP satellite devices.
     It offers some purely ‘ground-based’ functions such as Serial Flasher, Serial Monitor and HTML to Basic Conversion.
     It also uses a websocket connection to provide interaction with the remote ESP devices for file transfers, time synchronisation, OTA Server etc.

2.  Integral control web pages, served by the ESP for remote connection from a browser – these are totally independent of the Toolkit program.
     They offer script editing, viewing of output page(s), single file transfers, device configuration, OTA updates, etc.    
 
 
The AnnexToolkit must be used initially to flash an ESP device with the Annex WI-Fi Basic firmware using a hard-wired serial connection.
But after flashing, the device can be unplugged from the serial connection and relocated if wished, because the Toolkit is no longer essential.
It will undoubtedly still be useful, but for anything that does not require a direct physical serial connection the Toolkit can connect to, and interact with, a chosen ESP IP address by opening a remote wifi web-socket connection to the device, including for subsequent OTA firmware updates.
So most of the individual ESP script editing and testing will be done using the integral control web-pages in a browser.
 
 
Initially you may prefer to flash using the Yellow button which provides many varied examples to edit and run for getting a feel of what you can do.
Later you may prefer to flash using the Green button to retain existing project files and avoid unnecessary clutter.
An important feature of Annex is its ZIP capability, giving ability for project files to be conveniently saved to ZIP or loaded from ZIP, allowing valuable work to be archived.
This offers ‘selective’ loading of individual files (eg: from the “data-full.zip” and “data-min.zip” distribution examples which can be found in your computers parent Annex folder).
It not only offers a good way to keep project files grouped together by themselves, but also offers a handy way for distributing projects..
 
Here are a couple of demo videos to give some overview… for the sake of clarity they both start with a clean uncluttered device, but it is not an essential requirement.
 

Wall Switch  demonstrates copying a script from the website and pasting into the Editor, changing some parameters and saving the changes as different variants, then saving the files to computer as a project zip.

 
Skin Clock demonstrates downloading a project from the website and uploading it directly from the project ZIP to the remote ESP device – I called the project Skin Clock because it shows how to create a digital clock with embedded fonts and almost every aspect of the display is configurable according to personal taste using onscreen controls, and the chosen settings can be saved for later loading as a personalised clock ‘skin’.

Computer Utility Suite Program


Run AnnexToolkit program from your unzipped Annex WI-Fi Basic folder, ensuring it is not blocked by firewall or sandbox etc
As the Toolkit evolves over time some things may change but it should remain largely familiar..
The various Tabbed windows are explained below…
 

 
Serial Port Flasher 
 
Serial Upload Tab – the default Flashing screen
 
The first (default) screen is the Serial Upload Tab, used to Flash an ESP device using the Serial Com Port connection.

Hover the cursor over any of the controls to pop up a Tooltip description of the control.
 
 Read Module Info  blue button is non destructive, although it still needs the ESP device to be in flashing mode to read it.


 Flash Firmware Only  green button is non-destructive to any existing data, but will update the existing firmware by overwriting it with the update. 
 
 Flash Firmware + Data  yellow button is fully destructive by overwriting firmware and data, Data Size chooses either Min data or Full distribution.

 Erase the Flash Memory  the Big Red Button erases all flash memory to prepare the device for what would effectively be a new ‘virgin’ Flash.
 
Module Type contains a list of a few common type of modules – details for others may be added into the “modules.ini” text file.
Tick the ‘Advanced Options’ checkbox if you wish to display the selected modules parameters in the orange Advanced window.

Serial Port is your UART (FTDI) com port – it only shows as available if the port it is actually available. 
If you are not sure of your devices COM port, check what Toolkit ports are displayed without your device plugged in, then plug the device in and restart the Toolkit, then check to see the what new COM port is now available.

Speed is the baud rate setting for your devices UART (FTDI). 
If confident of your selected device and parameters, try flashing at the fastest speed, then drop to a slower speed if the flashing fails.
If not confident of settings, 115200 is a good solid speed that won’t take forever.

Module Size is the amount of flash memory the device has. Currently only 1Mb to 4Mb is supported (greater than 4Mb can be flashed as 4Mb).

The Serial Monitor button on the lower-left opens a special serial monitor that can swap serial port connection with the Flasher utility.

 
File Manager Tab 

File Manager Tab
 
The File Manager Tab is your ‘mission control’ nerve centre used for maintaining control of your remote ESP satellites.
Data displayed by items marked 1, 2, 3 ,5 (not 4) is all dependent on connection with the ESP device – so no connection means no valid data.

 1   Enter the appropriate target ESP IP Address, then click ‘Connect to ESP‘ button, the button will turn  green  when successfully connected. Clicking the green connected button will disconnect, clicking again will reconnect… connection status is also shown in the window below. it

 2   When connected, the ESP firmware version, ESP Ram Free, and ESP Flash Free (SPIFFS) are displayed in the window.
 
 3   When connected, the ESP Date and Time are displayed in the window. The ‘Sync Time‘ button provides a means of syncing date and time with the computer if the ESP has no internet access to sync from an NTP server (needs disconnect and reconnect to actually sync time).
 
 4   The ‘Local Files‘ window lists the Local Files and folders in the specified Folder Name that are available for upload. 
Use the ‘List Local Files‘ button to refresh the folder contents if changed. Multiple items can be selected (using Shift and CTRL keys). 
Click the ‘Upload Files‘ button to send the selected files through a web-socket wormhole up to the ESP device (assuming it is connected).
 
 5   The ‘Remote Files‘ window list the Remote Files and folders that exist on the connected ESP device. Multiple items can be selected. 
Click the ‘Download Files‘ button to copy the selected files (including their folder paths) to the specified Folder Name on computer. 
Caution – clicking the yellow ‘Delete Files’ button will permanently delete selected files.
 
 
OTA Tab 

OTA Tab
 
The OTA Tab is your own personal ‘Over The Air’ update server, allowing remote ESP devices to have their firmware updated via wifi.
Select your required wifi IP address from the dropdown list of available network interfaces, then click the ‘Start OTA Server‘ button.
When the OTA Server starts it will open a page in your browser which displays the URLs of the firmware (see below).
 
The appropriate URL should be copied and pasted into the OTA field of the Config Page.
NOTE:  the mini OTA is automatically selected by the firmware and is part of a special 2-steps OTA process permitting to update firmware > 512Kbytes.
It can evantually selected if the process must be done manually
 
Paste in the appropriate OTA url, click the ‘Save’ button, then click the ‘OTA Update’ button to start the firmware update (check the OTA log).
 
Backup / Restore Tab 

Backup / Restore Tab
 
You can create a firmware ‘binary’ backup image, or a data (SPIFFS) ‘binary’ backup image, or both separately, but not both combined.
Note that the appropriate device and com port parameters need to have already been selected in the main Serial Port Flasher tab.
Whereas the main Serial Port Flasher tab flashes the firmware pointed to in the Config tab path (currently build/annex.bin), the ‘Serial Restore Firmware’ button on this page allows flashing of any other specified binary firmware file instead (which need not necessarily be Annex Basic).
   

Config Tab

Config Tab

This is where the required paths are specified – paths and filenames may change.


UDP Tab 

UDP Tab
 
UDP (User Datagram Protocol) is a ‘connectionless’ network protocol where UDP nodes broadcast messages to the network then have no further interest nor any way of knowing if any other nodes exist or have received any broadcasts… so it has no handshaking or error-checkingcapability. 
 
Note that the UDP Console may assume the subnet address of a different network interface if others are present – so you may need to change the subnet shown in the ‘Remote IP address‘ to your ESPs wifi subnet, ie: 192.168.4.255  by default. 
(255 is the broadcast address – all network nodes ‘listen out’ for their own IP address plus the 255 broadcast address)
(so if you want to send a UDP message to node 123, you can address it uniquely as  192.168.4.123  or collectively as  192.168.4.255)
 
Only change the Remote Port number after you know what you are doing, otherwise you may be causing communications problems for yourself.
All the UDP nodes on a subnet have the potential to speak to each other, but only if they are using the same port number – if they are all using different port numbers they will all be isolated from each other… so the port number can be considered as their membership badge of recognition.
All the demos given here use port 5001 for consistency, you can change all the ports of your working projects for something else when done.
 
 
 
Serial Dev Kit
 
The Message to Send and Message Received areas are fairly self-explanatory, but if you are wondering about the 3 sliders at the bottom, they were used for a UDP network demo to control the RGB LED of the Serial Dev Kit Module shown on the right. 
 
 
 
 
 
 
 
HTML Converter Tab 

HTML Converter
 
The HTML (to Basic) Converter looks simple enough, and is … but there is actually more to it than meets the eye.
Firstly, be aware that the converted output has an extra line added at the top to initialise the variable (usually that’s wanted, but not always).
Notice also that nothing is added at the bottom, so nothing will be done with the converted variable until you make it happen, eg: HTML a$
Obviously the variable can be changed if you prefer (remembering all string variables should end with $ and are not case sensitive).
The default separator is the vertical bar “|“, which offers the convenience of including double-quotes within the text without causing problems  

Both the Paste and Copy buttons are smarter than they look – and to get that point across, ask yourself why they are even needed at all ?
They have been provided to add convenience… by doing away with the need to ‘select all’ or delete old contents.
Clicking ‘Paste’ will automatically overwrite previous HTML contents.
Clicking the ‘>>>’ convert button will automatically delete all old converted code to make way for the new.
Clicking ‘Copy’ will automatically select and copy all the converted contents to the clipboard.
Those are some thoughtful little touches, which will be particularly appreciated when the contents exceed the window size.


Syntax HighLight Tab

Syntax HighLight Tab
 
Allows colourising your offline text scripts with syntax highlighting similar to how it appears in the Editor. 
  Connecting
When the firmware boots up on the ESP device it automatically ‘serves up’ some integral web pages for users to connect to.
By default, the device configures itself as an AP (Access Point) at IP address 192.168.4.1 with a wifi SSID called ESP(plus MAC address).

 

A device on the same wifi network can connect to the ESP SSID and browse to the ESP IP address to open the default Output webpage,
If the wifi connection is broken, as for instance happens if the ESP reboots, any browser connections to the ESP will obviously be broken.
If the wifi connection is not configured to reconnect automatically, then the connection will remain broken until manually reconnected again.
The Output and Editor pages both have connection indicators which show green when connected but turn red when disconnected.

 

The red box shows the browser has lost connection with the ESP device… check for wifi SSID connection, then try clicking Reconnect button.
 
Whenever things are not behaving as expected, the first thing to check is that the browser has not lost connection to the ESP and turned red.
If the browser has lost connection, check if there is still wifi connection to the ESP, and if no ESP SSID is available, try rebooting the ESP device.
 
 
 
   Integral Web Pages
The default Output web page is where all script HTML output is sent to – it includes several menu buttons for opening various integral web pages:
 
Output Page 
The first button on the Output page allows opening a 2nd copy of the Output page if wished.
Why would you want 2 Output pages at the same time ? … mainly for testing purpose:
Annex-Wifi Basic allows up to 5 simultaneous connections – the computer Toolkit uses one, the Editor uses one, and the1st Output page uses one.
But more than 1 device can be connected, so it’s possible to have eg: a computer plus a smartphone plus a tablet all connected to the ESP device at the same time – the ability to open a 2nd Output window allows testing of multiple connections and alternative window sizes and resolutions etc.
TIP: The  ONHTMLRELOAD  command defines a branch label where the program will jump to when a reload of the Output html page is requested or a new client connects to the page … this offers opportunity to cater to different individual users on different devices.
 
 
Editor Page
 
If the ‘Connection‘ box turns red it is because the browser Editor page has lost connection with the ESP device – nothing you then do will register with the disconnected ESP, so anything you do (including any edits or other changes) will all be lost when the device is Reconnected.

To avoid losing unsaved edits after losing connection, do Select All and Copy, then Paste back again AFTER browser reconnection.

After a disconnection the Editors link to the source file is lost, so after reconnecting you must either Open or Save the file to re-link it to the editor. 

It is possible to click within the displayed ‘File to Run‘ window and edit the filename if wished, then Save to that new filename.
 
The ‘Advanced‘ checkbox allows loading another file into the editor window while still keeping the existing file loaded in the background and able to Run and Stop and view the results in the Output window. The original background file will need to be reloaded when Advanced is unticked.
 
Clicking the line numbers on the left will toggle a  red breakpoint, giving ability to Run or SingleStep the script up to the breakpoint(s).
 
The Syntax Highlighting toolbar icon allows to toggle syntax highlight on or off for the currently selected script Language syntax.
 
The 2 right-hand toolbar icons permit to insert or remove block comments for the selected lines (great for quickly switching out blocks of code).
 

The divider above the wlog (web log) window can be dragged down (using a right-hand drag handle) to change the ratio of the 2 windows.

The wlog window displays all system errors as well as browser output traffic – the checkbox underneath allows turning off wlog entries if preferred.
 
The 2 Variable windows allow specifying a variable name and monitoring associated variable value using the Get Variables button.
The Clear RAM button recovers all memory being used by variables.
 
The Immediate window permits executing commands without a script – eg: CLS then press Enter key to immediately clear the Output page.
Place cursor at the end of any history line the press Enter to execute that instruction again with having to retype it all back in.
 
NOTE: If the device connection is broken and remade, do a file Save or Open of the current editor file to re-register it again with the ESP.
NOTE: Leaving the Editor page, then returning back to it, will lose any unsaved edits, and return the editor to its default settings. 
 
Run, Pause, Stop 
These 3 buttons control the script operation – if the script is stopped Run starts it, if paused Run will un-pause it.  
These same buttons are also available from the Editor page, as are the File Manager and Config buttons. 
NOTE: all the Output page controls can be turned off from the Config page to provide a clean uncluttered user output screen if wished.
NOTE: uploading a different version of any web page does not automatically run it, so you should close the old, then open the new.
 
NOTEF2 button opens a context-sensitive Online Help page in the browser, which jumps to whichever Annex instruction the cursor is over.
Use the Help Search window to find all related help information about a particular topic, eg: serial
TIP: Use the context-sensitive help for debugging typo errors – Online Help will not jump to a mis-spelled Annex instruction it cannot recognise.
 

Config Page
 
Station Mode’ Name and Pass are for credentials needed to logon to a wifi router.
Ap Mode’ Name and Pass specify the SSID credentials needed for logon to the Annex-Wifi Basic Access Point.  
IP address, Subnet mask and Gateway are for a hard-coded static IP address – leave blank for DHCP client and 192.168.4.1 AP.
HTTP Port is normally port 80, but can be changed if blocked by firewalls etc.
Protected Access‘ requires that the appropriate credentials be entered to gain access to any Annex-Wifi Basic served web pages.
Time Zone‘ is the relative time offset from GMT, probably the same as your computers time zone.
NTP Server‘ is for specifying an alternative Time Server IP address or name (currently uses pool.ntp.org and time.nist.gov)
OTA url‘ is the url that is displayed when you ‘Start OTA Server’ from the ‘OTA’ tab of the computer utility tool.
Menu bar Disable‘ checkbox allows preventing any controls from being displayed on the user Output screen.
Run Default.bas at startup‘ checkbox allows the device to autorun the ‘default.bas’ script at power-on or reboot.
Save‘ button saves any changed settings to ‘/_root/config.ini’ to be read at power-on and reboots. 
Format‘ button wipes out all SPIFFS file entries to leave an empty filing system.
Restart‘ button causes the ESP device to reboot, therefore connections will obviously be broken.
OTA Update‘ button invokes Over The Air firmware update with the bin file pointed to by ‘OTA url’ if the OTA server is started.  
 
 
File Manager Page
 
Delete allows to delete individual files from SPIFFS.
View allows to display individual web pages, text files, stylesheets, javascripts.
Rename can rename individual files, or rename their paths to effectively move a file to a different folder.
Repair Disk uses some undocumented magic to do a chkdsk equivalent to the SPIFFS filing system, and can even repair corrupted SPIFFS.
Upload allows selecting individual files for uploading from computer.

NOTE
: these File Manager file operations only work on single files – so use the File Manager Tab in the Computer Tool for multiple file operations.