search

nutechsoftware / AlarmDecoder-IoT

AlarmDecoder Internet Of Things
Other
18 stars 8 forks source link

readme

AlarmDecoder IoT Network Appliance

Latest stable release Release Version Release Date Travis (.org) branch

Latest development branch Development branch GitHub last commit (branch) Travis (.org) branch

1. Overview

This project provides an example framework for building an IoT network appliance to monitor and control one or many alarm systems.

The AD2IoT network appliance integrates the AD2pHAT from AlarmDecoder.com and a ESP32-POE-ISO. The result is a device that easily connects to a compatible alarm system and publishes the alarm state to a public or private MQTT server for monitoring. The device can also be configured to initiate SIP voice calls, text messages, or e-mail when a user defined alarm state is triggered. The typical time from the device firmware start to delivery of the first state event is less than 10 seconds. Typical latency between an alarm event and message delivery is 20ms on a local network.

The device firmware is stored in the onboard non-volatile flash making the device resistant to corruption. With OTA update support the flash can be securely loaded with the latest version over HTTPS.

2. Tested and recommended hardware

3. Firmware

The firmware is already compiled for the ESP32-POE-ISO board and is available in the release page or via OTA(over-the-air) update. Currently the firmware is built with the following build flags 'stsdk' and 'webui'.

To switch to a specific build over the internet using OTA include the buildflag in the upgrade command.

If the upgrade fails it may be the result of low memory on the device. Try disabling features restart the device and try again. Example. webui disable Y. If all else fails install the latest release of the AD2IoT firmware over USB.

See the README-FLASH.MD inside the release file for instructions on flashing the firmware over the ESP32-POE-ISO USB port.

3.1. webUI build (webui) - alarmdecoder_webui_esp32.bin

This build uses the latest ESP-IDF v4.3 with the SmartThings driver is disabled.

3.2. SmartThings build (stsdk) - alarmdecoder_stsdk_esp32.bin

This build is compiled using the st-device-sdk-c-ref from the SmartThings github repo and has the webUI component disabled.

A few options are available as the AD2IoT device moves toward being certified and directly available in the SmartThings app. In order to Discover and adopt the AD2IoT device it needs to be visible in the "My Testing Devices" under the "Adding device" panel.

First you will need to enable Developer Mode in the app

Next decide if you want to build your own profile and layout or join the existing AlarmDecoder profile for how this device will be shown in the SmartThings app.

4. Configuring the AD2IoT device

Configuration of the AD2IoT is done directly over the USB serial port using a command line interface, or by editing the configuration file ad2iot.ini on the internal spiffs partition using ftp over a local network or by placing a config file named ad2iot.ini on an attached uSD card with a fat32 partition.

5. AD2Iot CLI - command line interface

5.1. Main commands

Modes: I Informational V Verbose D Debugging N Warnings and errors only(default)

- restart
```console
Usage: restart
    Save config changes and restart the device

Example:

top - 15:40:23.477 up 31 days TS: 2734823413319 Tasks: 14 Mem: 298328 total, 95508 free, 37876 min free

Name ID State Priority Stack CPU# Time %TBusy %Busy sys_evt 8 B 20 1048 0 4646 0.00 0.00 AD2 ota check 15 B 0 1368 0 50118679 0.00 0.00 Tmr Svc 4 B 1 1480 0 343028056 0.01 0.03 IDLE 3 R 0 1820 0 2692433658498 98.45 96.25 AD2 cli 6 R 2 1932 0 10170914876 0.37 1.25 tiT 7 B 18 2364 0 1134852575 0.04 0.05 emac_rx 9 S 15 3236 0 1149697995 0.04 0.02 httpd 13 B 5 3340 0 769 0.00 0.00 AD2 main 14 B 1 3468 0 11172565723 0.41 0.41 esp_timer 1 S 22 3672 0 29148 0.00 0.00 AD2 webUI 11 B 1 4192 0 48403756 0.00 0.00 AD2 GPIO COM RX 5 B 2 4288 0 18014970412 0.66 2.00 AD2 sendQ 10 B 1 5460 0 298731230 0.01 0.00 ftp daemon 12 B 1 7376 0 615 0.00 0.00

State legend 'B'locked 'R'eady 'D'eleted 'S'uspended Column legend Stack: Minimum stack free bytes, CPU#: CPU affinity TBusy: % busy total, Busy: % busy now

- upgrade
```console
Usage: upgrade [buildflag]

    Preform an OTA upgrade now download and install new flash
Options:
    buildflag               Specify a different build or use current if omitted
                            See release page for details on available builds

Options: N Disable(default) networking and allow a component to take over networking W Enable WiFi core driver E Enable Ethernet core driver arg Config string to pass to network driver Argument string name value pairs separated by &. Keys: mode,ip,mask,gw,dns1,dns2,sid,password Examples: WiFi DHCP with SID and password. netmode W mode=d&sid=example&password=somethingsecret Ethernet DHCP DNS2 override. netmode E mode=d&dns2=4.2.2.2 Ethernet Static IPv4 address. netmode E mode=s&ip=192.168.1.111&mask=255.255.255.0&gw=192.168.1.1&dns1=4.2.2.2&dns2=8.8.8.8

- switch
```console
Usage: switch <swid> [command] [<arg>]

    Configuration tool for ad2iot virtual switches

    This tool allows configuring ad2iot virtual switch that will change
     state based upon one more more filters and REGEX pattern matches.
    Up to 8 REGEX patterns for OPEN, CLOSE, and TROUBLE can be defined
    for complex state matching capabilities.

Commands:
    delete | -              Clear switch  settings
    default STATE           Default STATE [0]CLOSE(OFF) [1]OPEN(ON) [-1]UNKNOWN
    reset TIME              Auto rest TIME in ms 0 to disable
    types TYPE, TYPE,...    Message type filter list or blank to disable
    filter REGEX            Pre filter REGEX or blank to disable
    open IDX REGEX          OPEN event REGEX filter for IDX 1-8
    close IDX REGEX         CLOSE event REGEX filter for IDX 1-8
    trouble IDX REGEX       TROUBLE event REGEX filter for IDX 1-8
Options:
    switchId                ad2iot virtual switch ID 1-255
    IDX                     REGEX index 1-8 for multiple tests
    REGEX                   Regular expression or exact match string.
    TYPE                    Message types [ALPHA,LRR,REL,EXP,RFX,AUI,KPM,KPE,
                            CRC,VER,ERR,EVENT]

Common search verbs for type EVENT
      arm {STAY|AWAY}
      disarm
      power {AC|BATTERY}
      ready {ON|OFF}
      alarm {ON/OFF}
      fire {ON|OFF}
      chime {ON|OFF}
      exit {ON|OFF}
      programming {ON|OFF}
      zone {OPEN,CLOSE,TROUBLE} ZONE_NUMBER

Options: codeId Code ID 1 - 128

Options: reset Send hardware reboot to AD2pHat

- ad2config
```console
Usage: ad2config [<configString>]
    Configuration tool for AlarmDecoder hardware settings.

Options:
    configString            Name Value config string for the AlarmDecoder
                            device. Can be partial config.
                            Example set mode Ademco with default address 18.
                            ```ad2config mode=A&address=18```

Options: partId Partition ID 1-8 address For DSC 1-8 for Ademco use available keypad address. Use - to remove partition zoneList Optional Comma separated zone list for this partition Examples: Set default address mask to 18 for an Ademco system with zones 2, 3, and 4. partition 1 18 2,3,4 Set default send partition Id to 1 for a DSC system. partition 2 1 Show address for partition Id 2. partition 2 Remove partition Id 2. partition 2 - Note: address - will remove an entry.

- zone
```console
Usage: zone <zoneId> [- | <value>]
    Configuration tool for zone json description strings

Options:
    zoneId                  Zone ID 1 - 255
    -                       Delete entry
    value                   json string with type and alpha attributes
                            {"type": "smoke", "alpha": "TESTING LAB SMOKE"}

Options: mode Mode [S]ocket or [C]om port arg arg string for COM use for SOCKET use Examples: Set source to ser2sock client at address and port. ad2source SOCK 192.168.1.2:10000 Set source to local attached uart with TX on GPIO 4 and RX on GPIO 36. ad2source COM 4:36

###  5.2. <a name='ser2sock-server-component'></a>Ser2sock server component
Ser2sock allows sharing of a serial device over a TCP/IP network. It also supports encryption and authentication via OpenSSL. Typically configured for port 10000 several home automation systems are able to use this protocol to talk to the AlarmDecoder device for a raw stream of messages. Please be advised that network scanning of this port can lead to alarm faults. It is best to use the Access Control List feature to only allow specific hosts to communicate directly with the AD2* and the alarm panel.

####  5.2.1. <a name='configuration-for-ser2sock-server'></a>Configuration tool for Ser2sock server
```console
Usage: ser2sockd <command> [arg]

    Configuration tool for ser2sock server
Commands:
    enable [Y|N]            Set or get enable flag
    acl [aclString|-]       Set or get ACL CIDR CSV list use - to delete
Examples:
    ```ser2sockd enable Y```
    ```ser2sockd acl 192.168.0.0/28,192.168.1.0-192.168.1.10,192.168.3.4```

5.3. Web User Interface webUI component

This component provides a simple HTML5+WebSocket user interface with realtime alarm status using push messages over WebSocket. Buttons for Arming, Disarming, Exiting, and sending panic events. Panic buttons require pressing the button three times in 5 seconds to help prevent false alarms.

5.3.1. Configuration tool for webUI server

Usage: webui <command> [arg]

    Configuration tool for webUI server
Commands:
    enable [Y|N]            Set or get enable flag
    acl [aclString|-]       Set or get ACL CIDR CSV list
                            use - to delete
Examples:
    ```webui enable Y```
    ```webui acl 192.168.0.0/28,192.168.1.0-192.168.1.10,192.168.3.4```

5.4. SmartThings Direct Connected device.

Only available in stsdk firmware build

Direct-connected devices connect directly to the SmartThings cloud. The SDK for Direct Connected Devices is equipped to manage all MQTT topics and onboarding requirements, freeing you to focus on the actions and attributes of your device. To facilitate the development of device application in an original chipset SDK, the core device library and the examples were separated into two git repositories. That is, if you want to use the core device library in your original chipset SDK that installed before, you may simply link it to develop a device application in your existing development environment. For more info see https://github.com/SmartThingsCommunity/st-device-sdk-c-ref.

5.4.1. Configuration tool for SmartThings IoT client

5.5. Pushover.net notification component

Pushover is a platform for sending and receiving push notifications. On the server side, they provide an HTTP API for queueing messages to deliver to devices addressable by User or Group Keys. On the device side, they offer iOS, Android, and Desktop clients to receive those push notifications, show them to the user, and store them for offline viewing. See: https://pushover.net/

5.5.1. Configuration tool for Pushover.net notification

Usage: pushover (apptoken|userkey) <acid> [<arg>]
Usage: pushover switch <swid> [delete|-|notify|open|close|trouble] [<arg>]

    Configuration tool for Pushover.net notification
Commands:
    apptoken acid [hash]    Application token/key HASH
    userkey acid [hash]     User Auth Token HASH
    switch swid SCMD [ARG]  Configure virtual switches
Sub-Commands:
    delete | -              Clear switch notification settings
    notify <acid>,...       List of accounts [1-8] to use for notification
    open <message>          Send <message> for OPEN events
    close <message>         Send <message> for CLOSE events
    trouble <message>       Send <message> for TROUBLE events
Options:
    acid                    Account storage location 1-8
    swid                    ad2iot virtual switch ID 1-255.
                            See ```switch``` command
    message                 Message to send for this notification

5.6.1. Configuration tool for Twilio notifications

Usage: twilio (disable|sid|token|from|to|type|format) <acid> [<arg>]
Usage: twilio switch <swid> [delete|-|notify|open|close|trouble] [<arg>]

    Configuration tool for Twilio + SendGrid notifications
Commands:
    disable acid [Y|N]      Disable notification account(acid)
    sid acid [hash]         Twilio String Identifier(SID)
    token acid [hash]       Twilio Auth Token
    from acid [address]     Validated Email or Phone #
    to acid [address]       Email or Phone #
    type acid [M|C|E]       Notification type Mail, Call, EMail
    format acid [format]    Output format string
    switch swid SCMD [ARG]  Configure switches
Sub-Commands: switch
    delete | -              Clear switch notification settings
    notify <acid>,...       List of accounts [1-999] to use for notification
    open <message>          Send <message> for OPEN events
    close <message>         Send <message> for CLOSE events
    trouble <message>       Send <message> for TROUBLE events
Options:
    acid                    Account storage location 1-999
    swid                    ad2iot virtual switch ID 1-255.
                            See ```switch``` command
    message                 Message to send for this notification
    address                 EMail or Phone # depending on type
    format                  Template format string

If enabled the daemon will allow update of files on the attached uSD card. This allows for update of HTML or configuration settings from a secure host on the local network. To secure the FTP daemon the ACL needs to be configured to allow limited access to this service.

This daemon only supports one command and control connection at a time. Be sure to disable or limit the client used to a single connection or the client may appear to stall or timeout.

5.8.1. Configuration tool for ftp server

Usage: ftpd <command> [arg]

    Configuration tool for FTP server
Commands:
    enable [Y|N]            Set or get enable flag
    acl [aclString|-]       Set or get ACL CIDR CSV list
                            use - to delete
Examples:
    ```ftpd enable Y```
    ```ftpd acl 192.168.0.0/28,192.168.1.0-192.168.1.10,192.168.3.4```

6. Building firmware

6.1. PlatformIO

6.1.1. TODO: Setup notes

6.2. SmartThings device SDK build environment

6.2.1. Setup build environment

6.2.2. Configure the project

./build.sh esp32 AlarmDecoder-IoT menuconfig

6.2.3. Build, Flash, and Run

Build the project and flash it to the board, then run monitor tool to view serial output:

./build.sh esp32 AlarmDecoder-IoT build flash monitor -p /dev/ttyUSB0

(To exit the serial monitor, type Ctrl-].)

See the Prerequisites for full steps to configure and use ESP-IDF and the STSDK to build this project.

7. Example Output from ESP32 USB serial console

rst:0xc (SW_CPU_RESET),boot:0x1f (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0030,len:1760
load:0x40078000,len:12920
load:0x40080400,len:3604
entry 0x400805f0
I (432) cpu_start: Pro cpu up.
I (432) cpu_start: Single core mode
I (440) cpu_start: Pro cpu start user code
I (440) cpu_start: cpu freq: 160000000
I (440) cpu_start: Application information:
I (441) cpu_start: Project name:     alarmdecoder_stsdk_esp32
I (446) cpu_start: App version:      1.0.6p6-133-gc2cf6cd-dirty
I (452) cpu_start: Compile time:     Nov 20 2021 15:56:32
I (457) cpu_start: ELF file SHA256:  0123456789abcdef...
I (462) cpu_start: ESP-IDF:          4.3.0
I (466) heap_init: Initializing. RAM available for dynamic allocation:
I (472) heap_init: At 3FF80000 len 00002000 (8 KiB): RTCRAM
I (477) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM
I (482) heap_init: At 3FFB8E58 len 000271A8 (156 KiB): DRAM
I (488) heap_init: At 3FFE0440 len 0001FBC0 (126 KiB): D/IRAM
I (493) heap_init: At 40078000 len 00008000 (32 KiB): IRAM
I (498) heap_init: At 400953A0 len 0000AC60 (43 KiB): IRAM
I (504) !IOT: Starting AlarmDecoder AD2IoT network appliance version (AD2IOT-1093) build flag (webui)

!IOT: N (517) ESP32 with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
!IOT: N (527) Initialize NVS subsystem start. Done.
!IOT: N (547) NVS usage 17.51%. Count: UsedEntries = (331), FreeEntries = (1559), AllEntries = (1890)
!IOT: N (547) init partition slot 1 address 18 zones '2,5'
!IOT: N (557) init partition slot 2 address 23 zones '3,6'
!IOT: N (607) Mounting uSD card PASS.
!IOT: N (667) Initialize AD2 UART client using txpin(4) rxpin(36)
!IOT: N (667) Send '.' three times in the next 5 seconds to stop the init.
AD2IOT #
!IOT: N (5667) Starting main task.
!IOT: N (5667) 'netmode' set to 'E'.
!IOT: I (5667) UARTCLI: network TCP/IP stack init start
!IOT: I (5667) UARTCLI: network TCP/IP stack init finish
!IOT: I (5677) UARTCLI: ETH hardware init start
!IOT: I (5677) gpio: GPIO[12]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0
!IOT: I (5697) system_api: Base MAC address is not set
!IOT: I (5697) system_api: read default base MAC address from EFUSE
!IOT: I (5717) esp_eth.netif.glue: 01:23:45:67:89:ab
!IOT: I (5717) esp_eth.netif.glue: ethernet attached to netif
!IOT: I (5717) UARTCLI: DHCP Mode selected
!IOT: I (5737) UARTCLI: Ethernet starting
!IOT: I (5737) UARTCLI: ETH hardware init finish
!IOT: N (5777) TWILIO: Init done. Found and configured 4 virtual switches.
!IOT: N (5797) PUSHOVER: Init done. Found and configured 0 virtual switches.
!IOT: N (5797) WEBUI: service disabled.
!IOT: N (5797) MQTT init UUID: 41443245-4d42-4544-4410-0123456778ab
!IOT: E (5807) TRANS_TCP: DNS lookup failed err=202 res=0x0
!IOT: E (5817) MQTT_CLIENT: Error transport connect
!IOT: N (5867) MQTT: Init done. Found and configured 0 virtual switches.
AD2IOT #
!IOT: I (9737) UARTCLI: Ethernet Link Up
!IOT: I (9737) UARTCLI: Ethernet HW Addr 01:23:45:67:89:ab
!IOT: N (10867) SER2SOCKD: Init done. Service starting.
!IOT: N (11667) NEW IP ADDRESS: if(eth) addr(fe80:0000:0000:0000:9af4:abff:fe20:f14b) mask() gw()
!IOT: I (11667) esp_netif_handlers: eth ip: 192.168.111.123, mask: 255.255.255.0, gw: 192.168.111.1
!IOT: N (11677) NEW IP ADDRESS: if(eth) addr(192.168.111.123) mask(255.255.255.0) gw(192.168.111.1)
!IOT: N (11687) AD2 State change: {"ready":false,"armed_away":false,"armed_stay":false,"backlight_on":false,"programming":false,"zone_bypassed":false,"ac_power":true,"chime_on":false,"alarm_event_occurred":false,"alarm_sounding":false,"battery_low":false,"entry_delay_off":false,"fire_alarm":false,"system_issue":false,"perimeter_only":false,"exit_now":false,"system_specific":3,"beeps":0,"panel_type":"A","last_alpha_message":"****DISARMED****Hit * for faults","last_numeric_messages":"008","mask":1073712748,"event":"READY"}
!IOT: N (11777) AD2 State change: {"ready":true,"armed_away":false,"armed_stay":false,"backlight_on":false,"programming":false,"zone_bypassed":false,"ac_power":true,"chime_on":false,"alarm_event_occurred":false,"alarm_sounding":false,"battery_low":false,"entry_delay_off":false,"fire_alarm":false,"system_issue":false,"perimeter_only":false,"exit_now":false,"system_specific":3,"beeps":0,"panel_type":"A","last_alpha_message":"****DISARMED****  Ready to Arm  ","last_numeric_messages":"008","mask":1073450604,"event":"READY"}
!IOT: N (12667) NEW IP ADDRESS: if(eth) addr(2001:0db8:85a3:0000:0000:8a2e:0370:7334) mask() gw()
AD2IOT #
AD2IOT # help
Available AD2IoT terminal commands
  [ser2sockd, twilio, pushover, webui, mqtt, ftpd,
   restart, netmode, switch, zone, code, partition,
   ad2source, ad2config, ad2term, logmode, factory-reset, top,
   help, upgrade, version]
Type help <command> for details on each command.

8. Troubleshooting