Documentation for users switching to Annex and suggestions

[ByteCounter]

Hello

I am just getting started with Annex and am on the journey of getting familiar with Annex32.

Annex 32 is from what I’ve seen, a unique and powerful product in the world of ESP development. The online flash tool makes it super easy to setup ESP32 boards. However, there are a few rough edges that I feel need to be addressed for Annex to really shine. Eveything below is intended as constructive criticism.

Little known product. The word needs to get out about Annex as a good option for microcontroller and Internet Of Things development. I feel a name change to make it clear that it is ESP related (Annex-ESP32) but yet retains the Annex product name for future/different microcontroller ports.

Unfinished website. The unfinished website kind of looks unprofessional and is way less developed than the product! This gives the wrong impression of the software.

Better resources for beginners and those wanting to explore/switch to Annex.
A quick start guide to using annex, covering online/offline flashing and basic operation on how to write programs using the editor, viewing serial debugging (print statements), troubleshooting, etc. I have been making my internal notes as part of the learning process but if there is interest I would like to help writing a user's guide for Annex.

Online flash tool to easily setup Annex on your ESP32 board
[Local Link Removed for Guests]
Use Edge or Chrome or Opera web browsers – WILL NOT WORK WITH FIREFOX
(You must have the ESP USB serial port drivers for your OS already installed)

Online Help file (will redirect to latest)
[Local Link Removed for Guests]

Online help file 1.51.8
[Local Link Removed for Guests]

Online Web Serial Terminal (AnnexTerm)
[Local Link Removed for Guests]


While the on-line documentation is helpful (is there newer than [Local Link Removed for Guests] ?) as someone new to Annex32 these were some of my challenges:
Where to download the Annex Toolkit and how to set it up? I think the Toolkit is no longer needed?
Where was the online serial terminal? (didn’t realize this was using the serial UART for output) Found Online Serial Terminal (AnnexTerm) at [Local Link Removed for Guests]
It took a while before I found/understood the WLOG command, which is useful for debugging. It was not obvious that the text area under the editor is the debug window.

Some sort of wiki would also be a good idea, it is tiring going through forum messages looking for nuggets of information that may or may not be outdated as development occurs (example Annex Toolkit).

I almost feel bad for being critical in writing the above, as the work of one developer (correct me if I'm wrong) Annex is amazing.

Some specific suggestions (based on Annex32 CAN 1.52.4 LFS) and questions

1. Online Editor – needs dark mode, white background hurts my eyes after long sessions and some keyword highlighting is hard to read (for example orange “string” color on white background)

2. In the online editor the “beautify and check syntax” button should pop-up “Syntax OK, no errors found” otherwise if there are no errors, it is not clear that pressing the button did anything. I'm not sure about the beautify part of the description as I don't notice any changes after pressing it.

3. The help file says "If no parameters are specified in the “Config” page, or the connection is unsuccessful, it will default to AP (Access Point) mode with IP address 192.168.4.1 with the SSID composed of ESP(+ mac address)." Is there a way to have unsuccessful wifi retry reoccur for x minutes before defaulting to AP mode? This is to avoid power glitches or when wifi router is powered on later than ESP devices, which would (I assume) cause the ESPs to go into AP mode if the router hasn't booted yet. Or, can a digital input be checked on power-up to force ESP to go into AP mode?

4. For timers, what is the range of timer values, especially minimum value i.e. what is the practical realistic minimum timer interrupt that can occur, given that the ESP might be busy doing other things in the background (wifi, MQTT, display etc). This is important to know if trying to debounce inputs using a timer interrupt.

Thanks.

[cicciocb]

Hi ByteCounter and welcome to the group.

Thanks for your feedback that is very well accepted, as you say, as a positive criticism.

I think you've highlighted the major points already known and reported by other users, but I'm glad to see that despite these difficulties, you've come to the conclusion that Annex is worth it.

As you might know, I'm the developer of Annex, and I devote a significant portion of my time to it, alongside my work and family.

I try to keep the documentation as up-to-date as possible, knowing that, as with all software projects, documentation remains the most tedious thing to do. It's obvious that given the choice between spending days writing documentation and testing a new module or integrating a new feature, the choice seems obvious; it has to remain enjoyable for me and not another job.

Annex RDS is made by an hobbyist for the hobbyists, and this is the driver of this project.

I created a website back then where there's a very good tutorial written by Electroguard [Local Link Removed for Guests] , but it's obsolete as it refers to the first version of Annex for the ESP8266.

I've often asked for help in creating a new website but have never succeeded in convincing others to join me in this endeavor.

What I can say, however, is that despite the difficulties users may encounter, I'm seeing a steady increase in activity on the forum with thousands of daily connections, which makes me think that Annex is starting to spread; you're probably proof of that as many others simply don't communicate.

I think the best method is simply to ask questions on the forum, and someone will answer.
This is already the case every day, including for information that is present in the documentation.
Paradoxically, it's even a good thing because it can show the interest in the product and fill a database of information available to all users, unlike a product that is downloaded and used without ever being acknowledged.

Regarding your proposal for a user guide, I'm on board and I'll support any initiative in that direction; don't hesitate to share your notes, and we'll see if others will want to contribute.

Little known product. The word needs to get out about Annex as a good option for microcontroller and Internet Of Things development. I feel a name change to make it clear that it is ESP related (Annex-ESP32) but yet retains the Annex product name for future/different microcontroller ports.

The current name is Annex32 but yes, why not to call Annex-ESP32 ... maybe a poll on the forum?

Unfinished website. The unfinished website kind of looks unprofessional and is way less developed than the product! This gives the wrong impression of the software.

I need help for that, still open for volunteers

Better resources for beginners and those wanting to explore/switch to Annex.
A quick start guide to using annex, covering online/offline flashing and basic operation on how to write programs using the editor, viewing serial debugging (print statements), troubleshooting, etc. I have been making my internal notes as part of the learning process but if there is interest I would like to help writing a user's guide for Annex.

Same as for the help ... volunteers required
As I said above, don't hesitate to share your notes, and we'll see if others will want to contribute.

Online Editor – needs dark mode, white background hurts my eyes after long sessions and some keyword highlighting is hard to read (for example orange “string” color on white background)

If you are familiar with css, I can simply share the editor and the associated css you should be able to modify yourself

In the online editor the “beautify and check syntax” button should pop-up “Syntax OK, no errors found” otherwise if there are no errors, it is not clear that pressing the button did anything. I'm not sure about the beautify part of the description as I don't notice any changes after pressing it.

I think this also relates to the documentation / user guide

The help file says "If no parameters are specified in the “Config” page, or the connection is unsuccessful, it will default to AP (Access Point) mode with IP address 192.168.4.1 with the SSID composed of ESP(+ mac address)." Is there a way to have unsuccessful wifi retry reoccur for x minutes before defaulting to AP mode? This is to avoid power glitches or when wifi router is powered on later than ESP devices, which would (I assume) cause the ESPs to go into AP mode if the router hasn't booted yet. Or, can a digital input be checked on power-up to force ESP to go into AP mode?

Yes, you can connect the module in AP or STA mode using the code

For timers, what is the range of timer values, especially minimum value i.e. what is the practical realistic minimum timer interrupt that can occur, given that the ESP might be busy doing other things in the background (wifi, MQTT, display etc). This is important to know if trying to debounce inputs using a timer interrupt.

The time is in milliseconds, so the minimum is 1 ms; as Annex32 uses both cores of the CPU, many activities are handled in background so the "real" minimum time depends on what the program does. For example, playing a web radio streaming happens in background with a very little impact on the performances except when you start the streaming as it requires a given time for the initial connection to the remote server.

Again, thanks for your interest into Annex RDS and, as I always say, do not hesitate to ask on the forum for any other questions you may have, as there is a small group of active people who will certainly answer them.

cicciocb

[Electroguard]

Online Flasher
Wasn't going to nitpick for myself, but is worth mentioning for benefit of others that "Hard Reset" might be misunderstood (it fooled me) to be a hard reboot (cycle power off/on), whereas I believe it is a suggestion to boot into flashing mode (reboot while holding gpio0).

Which leads to some other related possible causes of Flasher confusion...
I have 3 types of 44pin S3 N16R8's which have dual USB type C connectors - they can all be powered using either USB connector, but they will only flash using the UART USB connector, whose position varies according to device type. So some devices must be flashed using the left connector, while others must use the right... but the onscreen message is confusing because it always reports everything as being "Connected Successfully", even when using the wrong USB connector.

If connected correctly it returns the correct device details and allows to flash with the selected firmware and options.

correct.jpg

If not connected correctly it still reports 'Connected Successfully', but also says 'Try hard reset' then waits indefinitely.

wrong.jpg

Rebooting the device just repeats the cycle, but rebooting with gpio0 (flashing button) held appears to boot into flashing mode exactly as if the device was connected correctly... but flashing is never successful.

flashmode.jpg

The solution is just to change to the other USB connector then refresh the browser.

Don't know if it can be made less confusing, but should be much easier now aware of what to look out for.

[cicciocb]

Hi Robin,
The message "connected successfully" means "connected successfully to the serial port", this enable to understand if the problem comes from the serial port link or from the module not talking.

The message "hard reset" means that, even if the serial port is connected correctly, the module don't communicate.

So far, all the modules I own, and there are quite a few, can be programmed using the WEB flasher via either the USB port or Serial port (for those modules equipped with dual ports).

Obviously, I must hold the boot button on the module while the module is connected to the PC
Edit :
I've just tested with an ESP32-S3 N8R2 using the USB port (holding the BOOT button while connecting to the PC).

It is important to know that, when flashing in USB mode, the module don't reset automatically but remains in download mode so it requires, as written in the text, to reset manually the module or disconnecting from the PC

image.png

P.S.
I use windows as main OS

[Electroguard]

Thanks for clarifying Francesco - so it sounds like if it is necessary to do a 'hard reset' to boot into flashing mode when in the 'wrong' USB port, the flashing button needs to be held in until after completion... which is obviously something important to bear in mind.
My observations were made with MX-Linux plus Chromium BTW, so I suppose things might vary with other OS/browser combinations.

[ByteCounter]

I try to keep the documentation as up-to-date as possible, knowing that, as with all software projects, documentation remains the most tedious thing to do. It's obvious that given the choice between spending days writing documentation and testing a new module or integrating a new feature, the choice seems obvious; it has to remain enjoyable for me and not another job.

I understand and agree. However I think a wiki would help complement the forum - experienced users could help you update the wiki as well as the forum.

I've often asked for help in creating a new website but have never succeeded in convincing others to join me in this endeavor.

Regarding help with website, I'm no good with HTML but I can assist with website text if someone else can handle the implementation.

Regarding your proposal for a user guide, I'm on board and I'll support any initiative in that direction; don't hesitate to share your notes, and we'll see if others will want to contribute.

I've already started working on it, will post draft here when it has reached a substantial state.

In the online editor the “beautify and check syntax” button should pop-up “Syntax OK, no errors found” otherwise if there are no errors, it is not clear that pressing the button did anything. I'm not sure about the beautify part of the description as I don't notice any changes after pressing it.

I think this also relates to the documentation / user guide

Just to be clear, what does the “beautify and check syntax” button in the editor window do? For me, it doesn't do anything when I press the button, even if there is a syntax error - it doesn't seem to reformat code either?

The help file says "If no parameters are specified in the “Config” page, or the connection is unsuccessful, it will default to AP (Access Point) mode with IP address 192.168.4.1 with the SSID composed of ESP(+ mac address)." Is there a way to have unsuccessful wifi retry reoccur for x minutes before defaulting to AP mode? This is to avoid power glitches or when wifi router is powered on later than ESP devices, which would (I assume) cause the ESPs to go into AP mode if the router hasn't booted yet. Or, can a digital input be checked on power-up to force ESP to go into AP mode?

Yes, you can connect the module in AP or STA mode using the code

OK but how long (or how many attempts) does ESP try to connect to the access point (that has been specified on the Config page) when connecting to wifi before giving up and switching to AP for configuration? Will it switch to AP mode only on first wifi connect failure (after power-up) or on any wifi failure (even after initial power-up)?

For timers, what is the range of timer values, especially minimum value i.e. what is the practical realistic minimum timer interrupt that can occur, given that the ESP might be busy doing other things in the background (wifi, MQTT, display etc). This is important to know if trying to debounce inputs using a timer interrupt.

The time is in milliseconds, so the minimum is 1 ms; as Annex32 uses both cores of the CPU, many activities are handled in background so the "real" minimum time depends on what the program does. For example, playing a web radio streaming happens in background with a very little impact on the performances except when you start the streaming as it requires a given time for the initial connection to the remote server.

1. I ask because in a non-interpreted language I would setup a base timer interrupt every 4mS or so and do input debounce etc based on this. My experience with other interpreted languages is that because of interpreter overhead and also background tasks (handling wifi or LCD display stuff etc) the pseudo timer interrupt cannot be very frequent (so that a reliable 4mS interrupt might be unrealistic).

2. You mentioned dual cores (ESP32 modules) with background tasks running on different cores. What happens for ESP chips that are only single core such as ESP32-S2, ESP32-C2 and ESP32-C3? Wouldn't the fastest attainable timer interrupt rate be less frequent for these chips since they have to handle everything with only one CPU core?

[cicciocb]

Hi again

Just to be clear, what does the “beautify and check syntax” button in the editor window do? For me, it doesn't do anything when I press the button, even if there is a syntax error - it doesn't seem to reformat code either?

It just check for the correspondence between IF / ENDIF, FOR / NEXT and so on; it also do an indentation of the loops for a better visibility. If a mismatch between the elements is found, raise an error message with the corresponding line. It does not check the syntax errors; I implemented long time ago because I was tired to see flat programs in pure OLD BASIC style, very hard to understand.
It is just a preliminary check of the code ... I use mostly to align all the indentations in the code.

OK but how long (or how many attempts) does ESP try to connect to the access point (that has been specified on the Config page) when connecting to wifi before giving up and switching to AP for configuration? Will it switch to AP mode only on first wifi connect failure (after power-up) or on any wifi failure (even after initial power-up)?

The module will try for around 25 seconds to connect to the access point and then it will switch to AP mode with the address 192.168.4.1. If the access point is found within this time, it will automatically reconnect to it if the WiFi is lost afterwards.
However, you can always, in your program, check if the connection is alive and connect to another Access Point.
You can even start the module in AP mode and then connect to a remote access with the command WIFI. CONNECT;
The important point is that the module must found the remote WiFi AP at the beginning otherwise it will switch in AP mode.

1. I ask because in a non-interpreted language I would setup a base timer interrupt every 4mS or so and do input debounce etc based on this. My experience with other interpreted languages is that because of interpreter overhead and also background tasks (handling wifi or LCD display stuff etc) the pseudo timer interrupt cannot be very frequent (so that a reliable 4mS interrupt might be unrealistic).

As I said, all depends on your application, you can achieve this timing but you should limit the activity on the other interfaces; anyway, I'm a little bit curious .... why you need a 4ms to debounce what ? Maybe you can do the same stuff in a different way. Do not forget that is an interpreter with a web server in background that answer at the external requests independently from the "basic" program running.

2. You mentioned dual cores (ESP32 modules) with background tasks running on different cores. What happens for ESP chips that are only single core such as ESP32-S2, ESP32-C2 and ESP32-C3? Wouldn't the fastest attainable timer interrupt rate be less frequent for these chips since they have to handle everything with only one CPU core?

Sure, the single core chip are more limited on concurrent activities even if, with a pure single program, they run at around the same speed. The main "disturbance" comes from the WiFi activity that happens in background.
I suggest to use the ESP32-S3 that is the more powerful chip of the series with a cost slightly higher than the classic ESP32

[ByteCounter]

The module will try for around 25 seconds to connect to the access point and then it will switch to AP mode with the address 192.168.4.1. If the access point is found within this time, it will automatically reconnect to it if the WiFi is lost afterwards.
However, you can always, in your program, check if the connection is alive and connect to another Access Point.
You can even start the module in AP mode and then connect to a remote access with the command WIFI. CONNECT;
The important point is that the module must found the remote WiFi AP at the beginning otherwise it will switch in AP mode.

How about a possible improvement for future firmware (WIFI.TIMEOUT)?
If you want to change the wifi timeout before the ESP automatically switches to AP mode you can use the WIFI.TIMEOUT command as in WIFI.TIMEOUT = 60 to change the WiFi timeout to 60 seconds. This setting in saved in non-volatile memory so it is remembered even after power-off or reset.
This would allow enough time after a power failure for wifi router to boot before ESP times out and goes into config AP mode. Some routers take some time before the wifi actually comes up.

I'm a little bit curious .... why you need a 4ms to debounce what ? Maybe you can do the same stuff in a different way. Do not forget that is an interpreter with a web server in background that answer at the external requests independently from the "basic" program running.

For traditional microcontroller programming I use a timer interrupt every 4mS or so for tasks like input debouncing (I check the state of inputs over multiple ISR passes to determine when an input is really on/off).
What I'm trying to do: I want to monitor a device that may output pulses typically 20 to 60mS wide every 300 to 500mS. It is critical not to miss any pulse activity.

I was looking for a way to have the ESP measure pulses (especially in background without blocking). I have searching helpfile for "pulse" but gotten no results until I came across the COUNTER command (more on that below).

I suggest to use the ESP32-S3 that is the more powerful chip of the series with a cost slightly higher than the classic ESP32

The S3 has a newer CPU core (LX7) vs the classic ESP32 (LX6) - any other reason to choose S3?

Below are other comments and questions:
In the editor, does the RUN command execute the last saved code or the current state of code (i.e. edits made after loading)? If this executes only the last saved code this could cause confusion as to why edits/bug fixes don't work!

Help file notes for 1.51.8
TIMERS
This section should mention that timer0 and timer1 resolution is in mS, with a warning that due to background tasks short timer intervals (1mS etc) possibly may be delayed. Also TIMER0 and TIMER1 function summaries should specify that timer resolution is in mS.

COUNTERS
From the description, the counters appear to work using a 100uS processor interrupt (1/10KHz), is this correct?
What is the maximum .COUNT and .PERIOD values?
Possible enhancement? Can implement a minimum width value so that there is a way to filter glitches or excessively short pulses? For example, you want to use COUNTER.COUNT(x) to count pulses longer than x uS (in my use case above I would want to filter pulses under 10mS)

Ping command - doesn't work in Immediate mode (as helpfile mentions) - can this be implemented in Immediate mode? Also summary should mention "ERR:Syntax error" will occur in Immediate mode.

[cicciocb]

How about a possible improvement for future firmware (WIFI.TIMEOUT)?
If you want to change the wifi timeout before the ESP automatically switches to AP mode you can use the WIFI.TIMEOUT command as in WIFI.TIMEOUT = 60 to change the WiFi timeout to 60 seconds. This setting in saved in non-volatile memory so it is remembered even after power-off or reset.
This would allow enough time after a power failure for wifi router to boot before ESP times out and goes into config AP mode. Some routers take some time before the wifi actually comes up.

A new command is not required as this can be done in the code, simply using WIFI.CONNECT ; increasing the timeout will delay the startup of the module as it will wait more time doing nothing. What you can do, at the beginning of your program, is to check if the module is in AP mode and then try to connect waiting for the establishment of the WIFI router.

For traditional microcontroller programming I use a timer interrupt every 4mS or so for tasks like input debouncing (I check the state of inputs over multiple ISR passes to determine when an input is really on/off).
What I'm trying to do: I want to monitor a device that may output pulses typically 20 to 60mS wide every 300 to 500mS. It is critical not to miss any pulse activity.

I was looking for a way to have the ESP measure pulses (especially in background without blocking). I have searching helpfile for "pulse" but gotten no results until I came across the COUNTER command (more on that below).

If your requirement is just to count the pulses, the COUNTER function should be good for you but if you plan to measure the length of each pulse (duration in ms, for example) this cannot be done. In this case the task should be done in H/W using the modules present in the chip (the PCNT or the RMT, for example)

The S3 has a newer CPU core (LX7) vs the classic ESP32 (LX6) - any other reason to choose S3?

It is simply the fastest chip of the series

In the editor, does the RUN command execute the last saved code or the current state of code (i.e. edits made after loading)? If this executes only the last saved code this could cause confusion as to why edits/bug fixes don't work!

The file must be saved before. The editor is completely offline and send the program only when it is saved.
Saving at each run should be resource consuming and add a unnecessary latency to the process.

TIMERS
This section should mention that timer0 and timer1 resolution is in mS, with a warning that due to background tasks short timer intervals (1mS etc) possibly may be delayed. Also TIMER0 and TIMER1 function summaries should specify that timer resolution is in mS.

noted

From the description, the counters appear to work using a 100uS processor interrupt (1/10KHz), is this correct?
What is the maximum .COUNT and .PERIOD values?
Possible enhancement? Can implement a minimum width value so that there is a way to filter glitches or excessively short pulses? For example, you want to use COUNTER.COUNT(x) to count pulses longer than x uS (in my use case above I would want to filter pulses under 10mS)

There is no fix interrupt rate, the pulse simply generates an interrupt that increase a counter.
The actual implementation, as it rely on H/W interrupts, should be quite reliable, at least until 10KHz.
There is also an undocumented feature (COUNTER.CPUFREQ) that use the PCNT H/W modules as a frequency counter (at least on the ESP32 classic) and, in this case, the limit should be 40MHz.
There is no way to filter the inputs but this could be done using H/W counters (the PCNT) as they have an input filter (even if the filtering window seems too little for your use case).
BUT this is not implemented
You can have more details in the Espressif Documentation (search for PCNT)

Ping command - doesn't work in Immediate mode (as helpfile mentions) - can this be implemented in Immediate mode?

I don't remember why but probably this is not possible.

Also summary should mention "ERR:Syntax error" will occur in Immediate mode.

Does this relates to the Ping command? Is not clear for me.

I think that relying your code with a 4ms interrupt will not work, the external async events will introduce a perturbation on the timing that will not be regular.
Probably you should rely this on an external H/W or implementing new functionalities using the internal H/W modules of the chip or using a simple external H/W ( a monostable with an AND port at the output, for example).

[ByteCounter]

A new command is not required as this can be done in the code, simply using WIFI.CONNECT ; increasing the timeout will delay the startup of the module as it will wait more time doing nothing. What you can do, at the beginning of your program, is to check if the module is in AP mode and then try to connect waiting for the establishment of the WIFI router.

Understood. Does it mean that on startup, the ESP will potentially delay up to 25 seconds (while waiting on Wifi connection) before your code starts running?

The file must be saved before. The editor is completely offline and send the program only when it is saved.

This "save before run" tip is extremely important and explains why I was confused at some of my experiment code not working (because I didn't save the code in the editor before running, so I was running old unmodified code!
I think to avoid doubt it might be a good idea to:
1. Edit the tooltop text (that appears when mouse is over RUN button) to include "You must SAVE your code before RUN for changes to take effect"
2. Is it possible to have a "CodeHasBeenEdited" flag that is reset by SAVE/SAVEAS button and set by any change in edit window? RUN button would then check flag and if code has been edited but not saved, the editor could ask whether to SAVE then RUN. This would help a lot towards preventing RUN without SAVE after editing code.

Also summary should mention "ERR:Syntax error" will occur in Immediate mode.
Does this relates to the Ping command? Is not clear for me.

Yes if the PING command is entered in Immediate mode the "ERR:Syntax error" is displayed.

I think that relying your code with a 4ms interrupt will not work, the external async events will introduce a perturbation on the timing that will not be regular.

Yes, this is what I was thinking. Probably need extra hardware to solve this.