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

© 2023 ZUMUNGO IoT Enabling Automation
All Rights Reserved