ZUMUNGO
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
USER GUIDE
rev. 3.1.3 March, 2021
WARNING !!!
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 | ZUMUNGO_xxxxxx where xxxxxx is last 6 characters of the MAC address of the relay board |
Factory set password for the AdHoc network | 123456789 (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 | 192.168.4.1 |
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 | Worldwide |
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
https://www.zumungo.com/get-started/
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
ZUMUNGO_XXXXXX 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.
123456789
Once connected to ZUMUNGO network go to this default IP address (not subject to change)
192.168.4.1
Use the default password for the board
Zumungu123456
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.
IMPORTANT !
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
192.168.1.150 for example your digits will be different
b) Send out this command using UDP protocol
CallAll
Protocol: UDP
IP address: 255.255.255.255
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 #
Example:
Server IP: 192.168.1.150 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
Example:
#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).
Example:
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
where
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: 192.168.1.150/1wire
The board will respond with JSON file like this
{
"board_name": "MatrixTest",
"IP": "192.168.1.178",
"ReportIP": "192.168.1.248",
"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"
}]
}
Were
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
Example:
Confirmation=201, MatrixTest, Button=name1, Onoff=0
Where
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
Example: 192.168.1.150/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 .
Example:
{
"board_name": "MatrixTest",
"IP": "192.168.1.178",
"ReportIP": "192.168.1.248",
"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
Example:
{
"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.
Example
1234#2
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
where
Matrix1 is the name of the board
x, y, z, … are the numbers of the buttons