Theremino

This section is dedicated to IotModule firmware development


If you are interested in getting new firmware developments here you can download beta firmware which has not yet been officially published on the Theremino website, along with the change log documentation!

 

You can contact me writing an email to : theremino dot lowpower at gmail dot com

 

You can translate this page using Chrome browser with Chrome Translate Extension installed.

 

At the moment the last insider firmware available is version 190, otherwise you can download the official firmware, v.182, in the IotHAL section on the Theremino site.

 

 
 

 

2021/02/28 - v.190

MD5 : 5b0d1d207b88bd1d2706b65f773e135f
SHA-256 : e62228cc392da473763439ec1dbbc65a7d7dc7d6ee51c20a6d8307802b8e57e0

Version v.190 is fully compatible with the official IotHAL windows application, v.1.4

v.190 Change log

The main changes introduced since version v.189 are:

Compatibility with Arduino ESP32 library v 1.0.5

Arduino ESP32 library v.1.0.5, based on ESP-IDF v3.3, available from 2021/02/23, introduces a change to a data type definition that prevents the sketch to compile

 

 
 

 

2020/11/18 - v.189

MD5 : 8dd4fac06cb438809ada4b06c4f5140f
SHA-256 : b724443b78c01363be291fcadf1bc15e402d2b846ce8bed299e86032f28f4aa6

Version v.189 is fully compatible with the official IotHAL windows application, v.1.4

v.189 Change log

The main changes introduced since version v.188 are:

PINOUT revision of ESP32-TTGO T7 v1.3

GPIO7 and GPIO11 have been removed, not usable since already connected to external flash chip, replaced by GPIO16 and GPIO17

ESP32-TTGO T7 v1.0 Pinout   ESP32-TTGO T7 v1.3 Pinout

New parameter for TX wifi power : IOTMODULE_WIFI_TX_POWER_INDEX

Possible values are:

10 = 19.5 dBm (default, used by previous firmware revision)
9 = 19 dBm
8 = 18.5 dBm
7 = 17 dBm
6 = 15 dBm
5 = 13 dBm
4 = 11 dBm
3 = 8.5 dBm
2 = 7 dBm
1 = 5 dBm
0 = 2 dBm

For example, to set the max TX power to 13 dBm:

#define IOTMODULE_WIFI_TX_POWER_INDEX 5

Optimization of the wifi connection speed if only one configuration column is defined

The wifi network scan operation in the case of multi SSID configuration introduces a small delay in the connection. If the multi SSID configuration is not required, i.e. if there is only one column for the SSID parameters in the configuration, the change introduced cancels this delay speeding up the connection to the limit.

 

 
 

 

2020/04/29 - v.188

MD5 : 1d313eef4eb5f15a80f3c47fd5779fe4
SHA-256 : aaeee6ae54dec7c4404478fb8ffa8ebffd6c8ce3f70de67f29732e5e163ae803

Version v.188 is fully compatible with the official IotHAL windows application, v.1.4

v.188 Change log

The main change introduced since version v.182 is the multi SSID configuration in IotModule.h.

This feature is very useful if you know in advance the access credential (SSID, password) of some Access Point you are going to connect, together with the type of IP connection (DHCP, static IP); you can prepare the configuration in advance, programming the firmware only once .

At every power up the module will search for a match between recognized and configured SSIDs, and it will continuously refresh the list of recognized SSIDs looking for a match. If a match is found and the connection is successful , the matched SSID will then be used as a reference : if the module temporarily loses wifi connectivity it will try to reconnect to he same SSID.

In order for the module to be able to connect to another network, its input power must be cycled off and on, or its reset button must be pressed.

Parameters description

 

This new release introduces some new parameters and some incompatibilites with parameters used before.

Multi word string parameters allow you to specify multiple items on one line; each item is separated from the other by one or more spaces.

As you will see in the examples, the multiword parameters form a sort of configuration organized in columns, where each column identifies a possible configuration.

IOTMODULE_STATIC_IP : deprecated, it must be removed from the configuration

IOTMODULE_WIFI_MODE : no more a numeric value, now is a single word string
it defines the main connection mode of the module. May be STATION or SOFTAP

IOTMODULE_WIFI_ASSOC : new single word string
it defines the mode association of a single configuration "column". May be STATION or SOFTAP

IOTMODULE_IP_MODE : new multi word string
it defines the IP level configuration mode. May be DHCP or STATIC

IOTMODULE_IP_IP : new multi word string
it defines the IPv4 module address. See examples

IOTMODULE_IP_NETWORK : new multi word string
it defines the IPv4 network mask. See examples

IOTMODULE_IP_GATEWAY : new multi word string
it defines the IPv4 network gateway address. See examples

IOTMODULE_IP_DNS : new multi word string
it defines the IPv4 address of the DNS server. See examples

IOTMODULE_WIFI_SSID : already used as single word string, now is a multi word string
it defines the wireless local area networking name

IOTMODULE_WIFI_PASSWORD : already used as single word string, now is a multi word string
it defines the wireless local area networking password

IOTMODULE_SPACE_CHAR : new single character
it defines one single character for space substitution in SSID and password words

How to convert configuration parameters in IotModule.h file from v.182 to v.188

Example 1 (station, dhcp)

v.182:

#define IOTMODULE_WIFI_MODE 0
#define IOTMODULE_WIFI_SSID " ssid1"
#define IOTMODULE_WIFI_PASSWORD " pwd1"

v.188:

#define IOTMODULE_WIFI_MODE "STATION"
#define IOTMODULE_WIFI_ASSOC    " STATION"
#define IOTMODULE_WIFI_SSID     " ssid1  "
#define IOTMODULE_WIFI_PASSWORD " pwd1   "
#define IOTMODULE_IP_MODE       " DHCP   "
#define IOTMODULE_IP_IP         "   -    "
#define IOTMODULE_IP_NETWORK    "   -    "
#define IOTMODULE_IP_GATEWAY    "   -    "
#define IOTMODULE_IP_DNS        "   -    "

Example 2 (station, static)

v.182:

#define IOTMODULE_WIFI_MODE 0
#define IOTMODULE_WIFI_SSID " ssid1"
#define IOTMODULE_WIFI_PASSWORD " pwd1"
#define IOTMODULE_STATIC_IP "192.168.11.1 192.168.11.254 255.255.255.0 192.168.11.254"

                                  (module IP)     (gateway IP)     (net mask)     (DNS IP)

v.188:

#define IOTMODULE_WIFI_MODE "STATION"
#define IOTMODULE_WIFI_ASSOC    "   STATION     "
#define IOTMODULE_WIFI_SSID     "    ssid1      "
#define IOTMODULE_WIFI_PASSWORD "     pwd1      "
#define IOTMODULE_IP_MODE       "    STATIC     "
#define IOTMODULE_IP_IP         " 192.168.11.1  "
#define IOTMODULE_IP_NETWORK    "255.255.255.0  "
#define IOTMODULE_IP_GATEWAY    "192.168.11.254 "
#define IOTMODULE_IP_DNS        "192.168.11.254 "

Example 3 (softap)

v.182:

#define IOTMODULE_WIFI_MODE 1
#define IOTMODULE_WIFI_CHANNEL 1

#define IOTMODULE_WIFI_MODE_PIN -1
#define IOTMODULE_WIFI_SSID " ssid1"
#define IOTMODULE_WIFI_PASSWORD " pwd1"

v.188:

#define IOTMODULE_WIFI_MODE "SOFTAP"
#define IOTMODULE_WIFI_CHANNEL 1
#define IOTMODULE_WIFI_MODE_PIN -1

#define IOTMODULE_WIFI_ASSOC    " SOFTAP"
#define IOTMODULE_WIFI_SSID     " ssid1 "
#define IOTMODULE_WIFI_PASSWORD " pwd1  "
#define IOTMODULE_IP_MODE       " DHCP  "
#define IOTMODULE_IP_IP         "   -   "
#define IOTMODULE_IP_NETWORK    "   -   "
#define IOTMODULE_IP_GATEWAY    "   -   "
#define IOTMODULE_IP_DNS        "   -   "

Example 4 (station with optional softap, dhcp)

v.182:

#define IOTMODULE_WIFI_MODE 0
#define IOTMODULE_WIFI_CHANNEL 1

#define IOTMODULE_WIFI_MODE_PIN 33
#define IOTMODULE_WIFI_SSID " ssid1"
#define IOTMODULE_WIFI_PASSWORD " pwd1"

v.188:

Is now possible to have two distinct pairs of SSID/password.

#define IOTMODULE_WIFI_MODE "STATION"
#define IOTMODULE_WIFI_CHANNEL 1
#define IOTMODULE_WIFI_MODE_PIN 33

#define IOTMODULE_WIFI_ASSOC    " STATION    SOFTAP"
#define IOTMODULE_WIFI_SSID     " ssid1      ssid2 "
#define IOTMODULE_WIFI_PASSWORD " pwd1       pwd2  "
#define IOTMODULE_IP_MODE       " DHCP       DHCP  "
#define IOTMODULE_IP_IP         "   -          -   "
#define IOTMODULE_IP_NETWORK    "   -          -   "
#define IOTMODULE_IP_GATEWAY    "   -          -   "
#define IOTMODULE_IP_DNS        "   -          -   "

New possibile configurations available with v.188

Example 5 (multi station, dhcp)

#define IOTMODULE_WIFI_MODE "STATION"
#define IOTMODULE_WIFI_ASSOC    " STATION STATION STATION STATION STATION STATION"
#define IOTMODULE_WIFI_SSID     " ssid1   ssid2   ssid3   ssid4   ssid5   ssid6  "
#define IOTMODULE_WIFI_PASSWORD " pwd1    pwd2    pwd3    pwd4    pwd5    pwd6   "
#define IOTMODULE_IP_MODE       " DHCP    DHCP    DHCP    DHCP    DHCP    DHCP   "
#define IOTMODULE_IP_IP         "   -       -       -       -       -       -    "
#define IOTMODULE_IP_NETWORK    "   -       -       -       -       -         "
#define IOTMODULE_IP_GATEWAY    "   -       -       -       -       -       -    "
#define IOTMODULE_IP_DNS        "   -       -       -       -       -         "


Example 6 (multi station, mixed dhcp + static)

#define IOTMODULE_WIFI_MODE "STATION"
#define IOTMODULE_WIFI_ASSOC    " STATION STATION STATION STATION STATION STATION     STATION        STATION "
#define IOTMODULE_WIFI_SSID     " ssid1   ssid2   ssid3   ssid4   ssid5   ssid6       ssid7          ssid8   "
#define IOTMODULE_WIFI_PASSWORD " pwd1    pwd2    pwd3    pwd4    pwd5    pwd6        pwd7           pwd8    "
#define IOTMODULE_IP_MODE       " DHCP    DHCP    DHCP    DHCP    DHCP    DHCP       STATIC          STATIC  "
#define IOTMODULE_IP_IP         "   -       -       -       -       -      -      192.168.11.1    172.20.1.1 "
#define IOTMODULE_IP_NETWORK    "   -       -       -       -       -          255.255.255.0   255.255.0.0"
#define IOTMODULE_IP_GATEWAY    "   -       -       -       -       -      -     192.168.11.254  172.20.1.254"
#define IOTMODULE_IP_DNS        "   -       -       -       -       -          192.168.11.254  172.20.1.254"


Example 7 (multi station, mixed dhcp + static, optional softap)

A low level on pin 33 selects the station modes, a high level selects the SofAP mode.

#define IOTMODULE_WIFI_MODE "STATION"
#define IOTMODULE_WIFI_CHANNEL 1
#define IOTMODULE_WIFI_MODE_PIN 33
#define IOTMODULE_WIFI_ASSOC    " STATION STATION STATION STATION STATION STATION    STATION        STATION   SOFTAP"
#define IOTMODULE_WIFI_SSID     " ssid1   ssid2   ssid3   ssid4   ssid5   ssid6      ssid7          ssid8     ssid9 "
#define IOTMODULE_WIFI_PASSWORD " pwd1    pwd2    pwd3    pwd4    pwd5    pwd6       pwd7           pwd8       pwd9 "
#define IOTMODULE_IP_MODE       " DHCP    DHCP    DHCP    DHCP    DHCP    DHCP       STATIC         STATIC     DHCP "
#define IOTMODULE_IP_IP         "   -       -       -       -       -      -      192.168.11.1    172.20.1.1     -  "
#define IOTMODULE_IP_NETWORK    "   -       -       -       -       -          255.255.255.0   255.255.0.0    -  "
#define IOTMODULE_IP_GATEWAY    "   -       -       -       -       -      -     192.168.11.254  172.20.1.254    -  "
#define IOTMODULE_IP_DNS        "   -       -       -       -       -          192.168.11.254  172.20.1.254    -  "


Example 8 (space substitution)

Spaces characters are already used as separators between words in multi word strings; if you need to insert one or more spaces in the SSID and/or password, you must identify one character not used yet in the credential pair.
This particular character must be specified in the dedicated directive and used in place of spaces in configuration words; these characters will be automatically replaced by spaces by the firmware during the configuration analysis, as you can see in this example.

#define IOTMODULE_WIFI_MODE "STATION"

#define IOTMODULE_SPACE_CHAR    '&'
#define IOTMODULE_WIFI_ASSOC    "      STATION         "

#define IOTMODULE_WIFI_SSID     " SSID&WITH&spaces     "
#define IOTMODULE_WIFI_PASSWORD " password&with&SPACES "
#define IOTMODULE_IP_MODE       "       DHCP           "
#define IOTMODULE_IP_IP         "         -            "
#define IOTMODULE_IP_NETWORK    "         -            "
#define IOTMODULE_IP_GATEWAY    "         -            "
#define IOTMODULE_IP_DNS        "         -           
"

Please note the use of single quotes in character definition.

In this case the effective SSID and password words will be internally converted from:

"SSID&WITH&spaces" and "password&with&SPACES"

to:

"SSID WITH spaces" and "password with SPACES"

Example 9 (how to avoid wrong configurations)

 


In order to avoid wrong configurations it is mandatory to place any character or word you like as a placeholder of unneeded configuration items; in this example the four placeholders needed for IP, NETWORK, GATEWAY and DNS items have been omitted in all DHCP columns . After the configuration analysis, only the first column with STATIC IP configuration will be taken in charge.

#define IOTMODULE_WIFI_MODE "STATION"
#define IOTMODULE_WIFI_ASSOC    "       STATION        STATION STATION STATION STATION STATION"
#define IOTMODULE_WIFI_SSID     "       ssid1          ssid2   ssid3   ssid4   ssid5   ssid6  "
#define IOTMODULE_WIFI_PASSWORD "       pwd1           pwd2    pwd3    pwd4    pwd5    pwd6   "
#define IOTMODULE_IP_MODE       "      STATIC           DHCP    DHCP    DHCP    DHCP    DHCP  "
#define IOTMODULE_IP_IP         "  192.168.11.1                                               "
#define IOTMODULE_IP_NETWORK    "  255.255.255.0                                              "
#define IOTMODULE_IP_GATEWAY    " 
192.168.11.254                                             "
#define IOTMODULE_IP_DNS        " 
192.168.11.254                                             "


This is the right configuration:

#define IOTMODULE_WIFI_MODE "STATION"
#define IOTMODULE_WIFI_ASSOC    "       STATION        STATION STATION STATION STATION STATION"
#define IOTMODULE_WIFI_SSID     "       ssid1          ssid2   ssid3   ssid4   ssid5   ssid6  "
#define IOTMODULE_WIFI_PASSWORD "       pwd1           pwd2    pwd3    pwd4    pwd5    pwd6   "
#define IOTMODULE_IP_MODE       "      STATIC           DHCP    DHCP    DHCP    DHCP    DHCP  "
#define IOTMODULE_IP_IP         "  192.168.11.1           -       -       -       -       -   "
#define IOTMODULE_IP_NETWORK    " 
255.255.255.0          -       -       -       -       -   "
#define IOTMODULE_IP_GATEWAY    " 
192.168.11.254         -       -       -       -       -   "
#define IOTMODULE_IP_DNS        " 
192.168.11.254         -       -       -       -       -   "


Notes on v.188

The keywords STATION, SOFTAP, DHCP, STATIC are case insensitive, may be used all uppercase, lowercase or in a mix.

SoftAP IP configuration mode is available exclusively in DHCP; STATIC mode has been removed.

Debug log messages, optionally configurable and available in the serial monitor window in Arduino IDE, have been improved to reflect available and configured SSID : this is an example.

The pinout type 3 has been introduced : it must be used with ESP32-TTGO T7 v1.3 module because pin 18 and 19 are crossed from ESP32-TTGO T7 v1.0 module.

 
 
 

 

Acknowledgements

I thank Livio who authorized me to make public the developments already available but not yet present on the official Theremino website.

This site is powered by great free services:

Gentoo, a highly flexible, source-based Linux distribution
Free DNS
Let's Encrypt
freepik
IPv6 Test