Matrix Keypad, Motion Sensor, Temperature sensor and other sensors


Software for ESP32 and ESP8266


Smart – Programmable – Controllable


Control by TCP and HTTP


Reports by TCP and HTTP






rev. 3.1.3 March, 2021





This is not a consumer software !


Basic skills and understanding of electrical circuits are required to properly install the software and operate the device!


Improper handling can result in property damage, bodily injury or death !

Table of Contents


  • Specifications


WiFi /controller module

ESP8266 or ESP32

AdHoc WiFi network SSID


where xxxxxx is last 6 characters of the MAC address of the relay board

Factory set password for the ​​ AdHoc network


(do not forget to change it to your own password for protection. Go to “WiFi settings” at the bottom of the main web page.)

IP address within the AdHoc WiFi network

Modes of operation

​​ a) simple button(s) press recognition and report

​​ b) combo of 2 buttons press recognition and report

​​ c) password entry recognition and report

d) motion sensor recognition and report

e) contact closure sensors recognition and report

f) 1 wire temperature sensors recognition and temperature report ​​ 


Web page settings

- setup passwords

- setup working hours, days for password validation

- setup GPIOs

- setup battery parameters

Source of time

Online NTP servers (high accuracy) or on board (manual setting, less accurate) if not connected to the Internet.

Time zones


TCP reports

- Single button number pressed

- Combo buttons pressed

- Password entry success or failure

- Sensor activation/deactivation

- Temperature

- Motion




    2. How to install the software in your device


Follow the "Get started" instructions at Zumungo's web site




If you complete all steps successfully than skip the next paragraph 3.

  • Connect to AdHoc WiFi Network


Skip this paragraph if you complete p. 2 succesfuly.



ZUMUNGO creates its own WiFi network with CCID



where XXXXXX is the unique board ID (last 6 characters of board's MAC address)


Use any WiFi capable device such as laptop, tablet, smart phone etc and find the ZUMUNGO network there and ​​ connect using the default password.




Once connected to ZUMUNGO network go to this default IP address (not subject to change)


Use the default password for the board




to open the web interface and setup the board.


Please do not forget to change the default password to your own password for your own protection. Go to “WiFi settings” at the bottom of the main web page to do that.


PLEASE NOTE: ​​ Android devices – smart phones and tablets perform this task better than iOS devices like iPhone and iPad. Please try an Android device if your iPhone or iPad fails to open Zumungo web pages.

4. Connect to home WiFi network.


Place ZUMUNGO powered device in an area where you have good coverage of your home WiFi network. This applies also to the final permanent destination of your ZUMUNGO powered device. If you are to control irrigation for example from your garage, first make sure you have decent WiFi coverage there.




    Never place your ​​ ZUMUNGO powered device in a metal enclosure if you want to control it over WiFi.


OPTION1 (if you are using p.3 approach) Select the name of your home WiFi network from the drop-down box, enter the password for your home WiFi network and click “connect”.




After few seconds your ZUMUNGO powered device will connect to your home WiFi network.


OPTION2 (if you are using p.2 approach) ​​ Do nothing. Your device will connect to your WiFi automatically


How do you find your device on your WiFi network is another question. Here you have few options as well


a) Go to your router's DHCP tables and look for the MAC address ending XXXXXX (see p.3 above for the meaning of XXXXXX). You will find the IP address next to it that looks like this ​​ for example your digits will be different


b) Send out this command using UDP protocol




Protocol: UDP

IP address:

Port: 60560





Go to any browser on your home WiFi network and enter the IP address of the board and you are in business. While at the router you may consider turning the dynamic IP address assigned by the router into a static one so that you always find your board at the same IP address.




  • Setup name and password for the board


Default name is Zumungo

Default password is: Zumungo123456


Go to home web page and log-in with the default password.

Scroll down to the bottom and click on “Board Setup” button.


At the top of the “Board Setup” page choose new name for your board and click “save”

Also at the top enter the existing password (default Zumungo123456 but enter your previously selected password if there is one).

Pick a new password and enter it twice. Also pick a password hint to remind you of your new password.

Click “Save password” and wait 10-20 sec as the board reboots after this change.




  • Setting up TCP port for the reports


Go to the "Board Setup" page (see screenshot above) and set the Server IP address and Server Port #




Server IP:   Server Port: 8991


Please note that if the device is programmed for battery operations than it goes into "deep sleep" after 15 sec of inactivity. Web page will not be available when device is in deep sleep. Wake it up by pressing any button in order to see the web page. The device will be "awake" while you are working at the web page and go to deep sleep after some period of inactivity.


  • Battery vs Line power


Select the power mode at the home web page of the device. Two options are available


Line power ​​ (default)

Battery power



If "battery" is selected than the device will go into deep sleep after 15 sec. of inactivity. Web pages will NOT be available when the device is in deep sleep mode. Press any key on the keypad or activate any sensor and the device will wake up and web pages will be available again.


In "battery" mode device will monitor the battery and will send out warnings when battery is low and needs change.

For proper operation you need to calibrate the battery from time to time. Measure the battery voltage and enter it into the box at the web page and click "calibrate" button. The box and the button are visible in battery mode only.

  • Setting up keypad user passwords and validity


Go to the web page of the device and setup as many passwords (a.k.a. pins) as needed.

The idea is to give different people different passwords with different validity periods and time slots. For example: manager, staff member, maintenance crew, family member, gardener, pool guy, maid, repair technician, etc.

Each password will have validity period and also validity time slots.

For example you may want to allow access to employees during certain days of the week and during certain working hours.

Working days and hours can be set up at the home web page.


  • GPIO configuration



You can setup the GPIOs to be used at the devices' web pages


4 GPIOs for the raws of the Matrix

4 GPIOs for the columns of the Matrix

1 GPIO for red ​​ LED

1 GPIO for green LED

3 GPIOs for additional stand alone buttons or contact closure sensors

3 GPIOS for relay outputs (to activate door lock for example)



Careful when setting up rows and columns for the matrix. First you have to take the ribbon cable in consideration and make them adjacent to each other. Second numbering of rows and columns does matter. Wrong arrangement will result in wrong button reports.

As far as each button press needs to wake up the board in battery mode not all GPIOs are good for keys, buttons and sensors. Follow the instructions at the web page. Also please check carefully that you use any GPIO only once.


Green LED is used to confirm button press to user as well as successful password entry. Red LED is used to indicate incorrect password or incorrect sequence when pressing buttons.


IMPORTANT ! ​​ Duplicate use of GPIOs can lead to unpredictable results including damage to the board and is strictly prohibited.


You can use digital sensors or additional stand alone on/off buttons ​​ in addition to the Matrix Keypad. Configure them at the bottom of the same web page "GPIO Setup". See p.10. Below for the use of "stand alone" buttons.


Also available are digital outputs that are named "Door opener" and "Panic" but can be used for any purpose.

"Door opener" is activated for few seconds after a successful password entry. More than one door is supported. See p.15 below for details.

"Panic" is activated permanently after 3 unsuccessful attempts to enter a valid password. Turn off power to the board to reset the "Panic".

    10. Single button press reports


    • Single button press of the matrix (non authorized)



The press of a single button of the Matrix keypad will produce this report to the TCP port


Confirmation=92, Matrix1, Bat=v.vv (in battery mode only)

Confirmation=201, Matrix1, Button=5x


Where "Matrix1" is the name of the board

v.vv is the voltage of the battery

x is the key pressed

x = 0,1,2,3...9, 10, 11, 12 or 13 for 4x4 matrix

x = 0,1,2,..9 for 4 x 3 matrix


where prefix 5 indicates single matrix button press that is not authorized (password was not entered before the button press. See below for authorized button presses).



Button * does not produce any TCP report as it is reserved for combo use with other buttons


Button # is reserved for use with passwords. It doesn't produce 201 report, however it does produce 92 report (in battery mode only, see above).


Report 92 (in battery mode only) is produced upon the wake-up of the board from deep sleep caused by the button press. If several buttons are pressed before the board going to deep sleep than only one report 92 will be produced.


    • Single button press of stand alone buttons (or contact closure sensors activation)


Press of any of the 3 stand alone buttons (or activation of contact closure sensor attached to the corresponding GPIO) will produce this TCP report


Confirmation=92, Matrix1, Bat=v.vv (in battery mode only)

Confirmation=201, Matrix1, Button=2x


Where "Matrix1" is the name of the board

v.vv is the voltage of the battery

x is the sensor # (GPIO assigned) that the button or ​​ sensor is attached values are 1,2 or 3


where prefix 2 indicates single stand alone button press


    • Motion sensor


Depending on the motion sensor that you have you may connect it directly to a GPIO that is assigned as one of the 3 Sensor inputs or if that doesn't work than you need to make the motion sensor drive a MOSFET transistor that is connected to the GPIO. The motion sensor must drive the GPIO low when motion is detected.

The board will produce the following report to the TCP port


Confirmation=92, Matrix1, Bat=v.vv (in battery mode only)

Confirmation=201, Matrix1, Button=2x


Where "Matrix1" is the name of the board

v.vv is the voltage of the battery

x is the sensor # (GPIO assigned) that the motion sensor is attached values are 1,2 or 3


  • Combo buttons press


Simultaneous press of button ​​ * ​​ and any other single button (different than button # ) of the matrix is considered combo button press. Combo doesn't work with the 3 stand alone buttons.


Combo button press will provide the following TCP report


Confirmation=92,Matrix1, Bat=v.vv (in battery mode only)

Confirmation=202,Matrix1, Function=x



Where "Matrix1" is the name of the board

v.vv is the voltage of the battery

x is the key pressed along with * key







  • Password entry


    • How to enter a password


Password can be any combination of characters as defined in the password setting at device's web page. Passwords are up to 8 characters long. Only characters that are on the matrix keypad are allowed


0, 1, 2 , 3 ..9 ​​ for 4x3 keypad

0, 1, 2, ...9, A, B, C and D ​​ for 4x4 keypad


Users can enter passwords in two ways


a) start with # and then enter the password and press # again at the end




#123456# ​​ will enter password 123456


b) just enter the password characters quickly one after another (timeout 2 sec) followed by idle time (idle time 3 sec).




123456 – keys pressed no longer wait than 2 seconds between key presses followed by 3 sec of no action will result in password entry of 123456.


Note: Password entry will be blocked for 5 minutes after 3 consecutive unsuccessful attempts to enter a password.


    • TCP report of password validation


The board will report the result of the password entry to the TCP port as follows


Confirmation=92,Matrix1, Bat=v.vv

Confirmation=202,Matrix1, Function=xx, Code=yyyyyyy




Matrix1 – is the name of the board


xx = 99 means a valid password

xx = 98 means a valid password and non valid timing

xx = 97 means invalid password


yyyyyyy – is the actual password that was entered.




  • Authorized button press


Buttons presses after the entry of a valid password are considered "Authorized".

Authorization expires after "authorized timeout" that is 3 sec.

Each matrix button press restarts the counter for "authorized timeout"

Only single button presses on the Matrix keypad are considered "authorized"

Combo buttons as well as the stand alone buttons (sensors) are not subject to "authorize" and they report the same way after the entry of a password as they would without a password.


The report of Authorized button presses are similar to the reports for single button presses without the prefix "5".


Confirmation=201, Matrix1, Button=x


Where "Matrix1" is the name of the board

v.vv is the voltage of the battery

x is the key pressed

x = 0,1,2,3...9, 10, 11, 12 or 13 for 4x4 matrix

x = 0,1,2,..9 for 4x3 matrix


















  • "1 wire" temperature sensors


"1 wire" temperature sensors such as the popular DS18B20 are widely available and are inexpensive to buy and easy to install. They come in various enclosures including waterproof one. One advantage of the "1 wire" technology is that you can hook multiple sensors in parallel to measure temperature in different points. Zumungo enabled board will report the readings of up to 20 sensors while using only one GPIO.


    • Connection


Connect the "output" of the temperature sensor to the GPIO selected to be your 1 wire

See the documentation of your chosen 1 wire sensor about how to connect the 3 wires coming out of it. Typically one is ground the other connects to 3.3V and the third one is the data wire. Resistor of 4.7K is recommended between the data wire and Vcc = 3.3V.


IMPORTANT: Do not use any voltage higher than 3.3V as it may damage your MCU.


    • Reading the temperature


Go to http://IPaddress/1wire


For example:


The board will respond with JSON file like this



"board_name": "MatrixTest",

"IP": "",

"ReportIP": "",

"scan": "25000",

"sensors": [{

  "name": "name1",

  "hex": "28fffa3571194ab8",

  "TempF": "74.64",

  "TempC": "23.69",

  "TriggerF": "85.00",

  "hystF": "2.00",

  "val": "17b",

  "triggered": "1",

  "triggered_level": "0",

  "live": "1",

  "error": "0"






scan – is the scan interval in ms This is how often the Zumungo powerd board will measure the temperature.


name: is the name of the sensor default names are name1, name2, name3 … All names can be changed for convenience, however it is the hex value that matters when identifying a sensor for the purpose of controlling it.


hex – unique hex value attribute for each sensor not subject to change. Must be used in control (see below) to properly isentify a sensor.


TriggerF – is the temperature in F degrees at which the board will get "triggered" and will send out a message to the TCP port about it (see below).


HystF – hysteresis in degrees F. This is being subtracted from the trigger temperature on the way down in order to avoid jitters.


​​ val – reserved for use with other 1 wire devices than temperature sensors


triggered = 1 if triggered and 0 if not triggered


triggered_level – can be 0 or 1. If 1 than it reverses the "triggered" values 0 and 1


live = 1 if sensor is connected and active = 0 if sensor is temporarily disconnected. ​​ Even if you disconnect permanently and discard the sensor and replace it with another one it will still show in the reports with live=0. The new sensor will be with another name.


error = 0 if there are no errors and error = error # if there is an error


    • Triggered condition and TCP report


Zumungo powered board will report when a trigger happens to the TCP port with a message like in this




Confirmation=201, MatrixTest, Button=name1, Onoff=0




MatrixTest is the name of your Zumungo powered board

name1 – the name of the temperature sensor ​​ (up to 20 sensors can be hooked to the same board using one GPIO only)

Onoff = 1 if triggered and ​​ 0 if not triggered (subject to reversal by the parameter "triggered_level" see above)


triggered (Onoff = 1) when  ​​ ​​ ​​ ​​​​ Current Temperature (in F degrees) < TriggerF

not triggered (Onoff=0) when ​​ Current Temperature (in F degrees) > TriggerF+HystF


    • Setting up parameters


Setup happens by HTTP POST to the IP address of the Zumungo powered board and the HTTP port as it is set in the board settings (default is 80).


Headers for the POST


Authorization "password for the board default "Zumungo123456" see p.5 above"

Content-type ​​ application/json


Destination for the POST


IP address/1wire




Body of the POST


JSON file identical to the report JSON (see 14.2 above). Only highlighted fields are subject to a setup. All other fields can be omitted or they will be ignored if present .




​​ {

"board_name": "MatrixTest",

"IP": "",

"ReportIP": "",

"scan": "25000",

"sensors": [{

  "name": "name1",

  "hex": "28fffa3571194ab8",

  "TempF": "74.64",

  "TempC": "23.69",

  "TriggerF": "85.00",

  "hystF": "2.00",

  "val": "17b",

  "triggered": "1",

  "triggered_level": "0",

  "live": "1",

  "error": "0"




Only "hex" field is mandatory for setting up a particular sensor out of the highlighted fields as it uniquely identifies the sensor. Of course at least one more filed has to be used for the command to make sense.


Example 1 ​​ (this is a valid command that changes the name of the sensor only) :



  "sensors": [{

  "name": "Outdoors",

  "hex": "28fffa3571194ab8",





Example 2 ​​ (this is a valid command that changes Trigger temperature and Hysteresis)




  "sensors": [{

  "hex": "28fffa3571194ab8",

  "TriggerF": "89.00",

  "hystF": "1.55"






Example3 ​​ (this is a valid command that changes the scan interval only) :


​​ {

"board_name": "MatrixTest",

"scan": "25000"



    • Deleting sensors


As mentioned above sensors removed from the system will remain in the reports, reported as live=0. In order to remove a sensor from the system it must be deleted explicitly.


Use the same POST JSON technique as described above with POST Body as in this




​​ {

  "sensors": [{

  "hex": "28fffa3571194ab8",

  "delete": "1"




  • Outputs – door opener or panic


Up to 3 outputs can be configured in your Zumungo powered board to be used for door opener or panic alarm (siren).


Go to GPIO setup web page to do so.



Panic(Siren) output will be activated after 3 unsuccessful attempts to enter a password at the keypad.


Door opener output will be activated after a successful entry of a password and selection of one of the three available outputs.






will activate door lock #2 if your password is 1234


Please note that the output signal is coming from a regular GPIO. It has positive polarity and voltage is 3.3V. If this signal is not strong enough to drive your door opener or alarm than some additional circuitry may be needed. Using opto-coupler is a good idea and strongly recommended to prevent any external voltage reaching your GPIO port and damaging your board.

  • Error messages




Following error messages are being send to the TCP server


Error=203,Matrix1, too many buttons pressed simultaneously, Buttons=x, y, z, ...


Error=204,Matrix1, button was hold pressed for more than 5 sec, Button=x




Matrix1 is the name of the board


x, y, z, … are the numbers of the buttons

© 2024 ZUMUNGO IoT Enabling Automation
All Rights Reserved