Theremino

This section is dedicated to IotModule firmware development


If you are interested in the making of 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!


At the moment the last insider firmware available is  v.188


MD5 : 1d313eef4eb5f15a80f3c47fd5779fe4

SHA-256 : aaeee6ae54dec7c4404478fb8ffa8ebffd6c8ce3f70de67f29732e5e163ae803

The v.188 version is fully compatible with the official IotHAL windows application, v.1.3


Otherwise you can download the official firmware, v.182, in the IotHAL section on the Theremino site.


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



2020/04/29 - 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 place holder of unneeded configuration items; in this example the four place holders 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.


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:

Free DNS

Let's Encrypt


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