Getting Started

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.