Matrix Keypad


Software for ESP32 and ESP8266


Smart – Programmable – Controllable


Control by TCP and HTTP


Reports by TCP and HTTP






rev. 3.1.1 July, 2019





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 xxxxxxxxxxxx is the unique 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

3 modes – a) simple button(s) press recognition and report

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

 ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​ ​​​​ c) password entry recognition and 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

6 – Eastern, Central, Mountain, Pacific, Alaska, Hawaii

TCP reports

- Single button number pressed

- Combo buttons pressed

- Password entry success or failure




    2. How to install the software in your device



  • Connect to AdHoc WiFi Network


ZUMUNGO creates its own WiFi network with CCID



where xxxxxxxxxxxx is the unique MAC address of the relay board


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 relay 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.



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.


While connected to the adhoc network ZUMUNGO (see previous chapter) go to the main web page and take a note of the 12 character MAC address that looks similar to this with different digits and letters.


MAC Address 00-12-34-de-45-ab-6c


After you have taken the MAC address on a piece of paper than go to the bottom of the page and

click the button “WiFi settings” at the bottom.


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.


How do you find it is another question. To do so you need to go to your router's DHCP tables and look for the MAC address you just took note of. You will find the IP address next to it that looks like this ​​ for example your digits will be different


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 web page of the device and enter the IP address and Port #




Please note that the device is programmed for battery operations and 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.


  • Calibrating the battery


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.

  • Setting up passwords and validity


Go to the web page of the device and setup as many passwords as needed.

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

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




  • 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

4 GPIOs for additional stand alone buttons or contact closure sensors

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


Careful when setting up raws 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 raws and columns does matter. Wrong arrangement will result in wrong button reports.


    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

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 (see above).


Report 92 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 4 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

Confirmation=201, Matrix1, Button=2x


Where "Matrix1" is the name of the board

v.vv is the voltage of the battery

x is the key pressed x = 1, 2, 3 or 4


where prefix 2 indicates single stand alone button press



  • 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 4 stand alone buttons.


Combo button press will provide the following TCP report


Confirmation=92,Matrix1, Bat=v.vv

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 set in the settings default 2 sec) followed by idle time (idle time set in the settings default 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 subject to setting at the web page (default 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


















14 Error messages


Following error messages are being send to 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

© 2020 ZUMUNGO IoT Enabling Automation
All Rights Reserved