Merge pull request #38 from lkankowski/develop

Release 2.4.0

Author: lkankowski

.github/workflows/main.yml

@@ -1,6 +1,6 @@
 # This is a basic workflow to help you get started with Actions
 
-name: PlatformIO CI
+name: Build & Test
 
 # Controls when the workflow will run
 on:
@@ -39,15 +39,25 @@ jobs:
         with:
           path: ~/.platformio
           key: ${{ runner.os }}-${{ hashFiles('**/lockfiles') }}
+      
       - name: Set up Python
         uses: actions/setup-python@v2
+      
       - name: Install PlatformIO
         run: |
           python -m pip install --upgrade pip
           pip install --upgrade platformio
+      
       - name: Configure Multi-Relay
         run: cp include/config.h.sample include/config.h
-      - name: PlatformIO - run build
-        run: pio run -e mega2560 -e nano328 -e native
+      
+      - name: PlatformIO - run build all env
+        run: pio run `grep -Eo '^\[env:[a-z0-9\-]*' platformio.ini | cut -c6- | sed 's/^/-e /' | paste -sd ' ' -`
+        
+      - name: PlatformIO - run build with DEBUG_*
+        run: pio run -e mega2560-serial
+        env:
+          PLATFORMIO_BUILD_FLAGS: -D DEBUG_COMMUNICATION -D DEBUG_ACTION -D DEBUG_STARTUP -D IGNORE_BUTTONS_START_MS=2000
+      
       - name: PlatformIO - run test
         run: pio test -e native

.gitignore

@@ -4,3 +4,4 @@ workspace.code-workspace
 *.hex
 include/config.h
 include/config.h.local
+shared/platformio_local.ini

README.md

@@ -1,30 +1,67 @@
+# Multi-Relay 2
+
+Stable build Status ![](https://github.com/lkankowski/arduino-multi-relay2/actions/workflows/main.yml/badge.svg?branch=master), 
+Develop build Status ![](https://github.com/lkankowski/arduino-multi-relay2/actions/workflows/main.yml/badge.svg?branch=develop)
+
 * [About](#about)
 * [Get Started](#get-started)
 * [Configuration](#configuration)
 * [Debugging](#debugging)
 * [Expander](#expander)
 * [Troubleshoting](#troubleshoting)
 
-
-# About
-Arduino program to handle relays and control them using switches with support for double-click and long-press. Integration with home automation systems is possible through MySensors integration.
-Configuration is very simple - one line for a single relay and one line for single switch
-Every switch support debouncing, multiple types of switches and additional actions like double-click and long-press - everything in a single line of configuration. Relays can be configured as LOW/HIGH level trigger, startup state ON or OFF and impulse type.
+## About
+Arduino program to handle relays and control them using switches with support for double-click and long-press. Integration with home automation systems is possible through MySensors integration over serial, LAN or MQTT.
+Configuration is very simple - one line for a single relay and one line for single switch.
+Every switch support debouncing, multiple types and additional actions like double-click and long-press - everything in a single line of configuration. Relays can be configured as LOW/HIGH level trigger, startup state ON or OFF and impulse type.
 One relay can have one or more switches, or not at all if you want to control it only by home automation system.
 
-# Get Started
+### Supported platforms and hardware
+* Arduino Mega2560 and other AVR ATmega family
+* ESP8266
+* ESP32 - Experimental! Tests with LAN worked fine, but had no luck with MQTT
+* Ethernet (LAN or MQTT)
+  * W5100
+  * ENC28J60
+* expanders (described later in this doc)
+  * MCP23017
+  * PCF8574
+
+
+## Get Started
 
-## Create config file
+### Download
+Most convinient is to clone the repo, but you have to have installed `git`:
+```
+git clone https://github.com/lkankowski/arduino-multi-relay2.git
+```
+You can also download zip file.
+
+### Create config file
 Copy file "config.h.sample" into "config.h". There is sample configuration you need to examine and customize for your own needs.
 
-## Build
+### Build
 You need PlatformIO - it is free and you can get it here https://platformio.org/platformio-ide. Arduino IDE is not supported.
-By default sketch is built for Arduino Mega 2560. Build options can be customized in `platformio.ini` - more information in separate sections.
+By default sketch is built for Arduino Mega 2560, but you choose environment that suits your needs.
+Build options can be customized in `platformio.ini` - more information in separate sections.
 Remote upload (ie. Arduino connected to Raspberry PI) is supported. For more information read https://docs.platformio.org/en/latest/core/userguide/remote/cmd_agent.html.
 
-# Configuration
+### Updating
+If you have 'git', just type `git pull`. Otherwise download zip file and extract to new directory - remember, to backup 'config.h'.
+It is also convinient to have 'config.h' someware else, then you can use symbolic link. In Windows you have 2 options:
+
+CMD:
+```
+mklink "<your local config directory>\config.h" "<your repo directory>\include\config.h"
+```
+or PowerShell (assuming that you run in main repo directory):
+```
+Start-Process -Verb RunAs -FilePath "powershell" -ArgumentList "-NoExit","-command","New-Item -Path '$(Get-Location)\include\config.h' -ItemType SymbolicLink -Value '<your local config directory>\config.h'"
+```
 
-## Main config file "config.h"
+## Configuration
+
+### Main config file "config.h"
 ```
 const RelayConfigDef gRelayConfig[] PROGMEM = {
   {sensor id, relay pin, relay options, relay dependOn, relay description}
@@ -37,6 +74,7 @@ Params description:
   * RELAY_TRIGGER_LOW or RELAY_TRIGGER_HIGH - required, trigger level
   * RELAY_STARTUP_ON or RELAY_STARTUP_OFF - optional, startup state
   * RELAY_IMPULSE - optional, relay is turned on only for short period of time (defined in constant RELAY_IMPULSE_INTERVAL, 250ms by default), ignored for DING_DONG and REED_SWITCH buttons
+  * RELAY_INDEPENDENT - described in (#dependent-relays)
 * relay dependOn - ID of relay that needs to be turned on before this one
 * relay description - reported on MySensor Gateway, can help identify device on initial configuration in Home Automation System, max. 30 chars, can be empty ("")
 
@@ -57,23 +95,21 @@ Params description:
 * double-click relay id - sensor id used in relay configuration, -1 when not used, ignored for DING_DONG/REED_SWITCH
 * button description - debug only information, max. 30 chars, can be empty ("")
 
-
-## Example config with REED_SWITCH
+### Example config with REED_SWITCH
 ```
 const RelayConfigDef gRelayConfig[] PROGMEM = {
-  {26, 31, RELAY_TRIGGER_HIGH, "Garage Door"},
+  {26, 31, RELAY_TRIGGER_HIGH, -1, "Garage Door"},
   ...
 };
 const ButtonConfigDef gButtonConfig[] PROGMEM = {
   {43, REED_SWITCH, 26, -1, -1, "Garage Door reed switch"},
   ...
 };
 ```
-In this case relay 26 is always reported throught as S_DOOR sensor, i.e. in Home Assistant this relay can be found in entities as binary_sensor.multi_relay_0_26.
+In this case relay 26 is always reported throught as S_DOOR sensor, i.e. in Home Assistant this relay can be found in entities as binary_sensor.
 
-
-## Dependent relays
-The "dependOn" option in relays configuration is intended for turning ON and OFF power supplies, not to create scenes.
+### Dependent relays
+The "dependOn" option in relays configuration is intended for turning ON and OFF power supplies or simple scenes.
 For example, you have 12V power supply and two 12V LED lights:
 ```
 ...
@@ -85,8 +121,18 @@ For example, you have 12V power supply and two 12V LED lights:
 When you turn on _LED Strip_ and/or _Stairs light_, then _Power supply 12V_ will be automatically turned on.
 _Power supply 12V_ will be automatically turned off, when all parent devices will be turned off.
 
+Additionaly there is one way option:
+```
+...
+  {11, A1, RELAY_TRIGGER_LOW, 12, "Hall light"},
+  {12, A2, RELAY_TRIGGER_LOW | RELAY_INDEPENDENT, -1, "Stairs light"},
+...
+```
+In this variant, when you turn on _Hall light_, also _Stairs light_ will turn on,
+but when you turn off _Hall light_, _Stairs light_ will remain on.
+
 
-## Additional config
+### Additional config
 Optional configuration only if you want to customize the script.
 
 MONO_STABLE switches can trigger ralay when switch is pressed (LOW) or when switch is released (HIGH):
@@ -119,37 +165,59 @@ Sketch description reported via MySensors to Home Automation System:
 const char MULTI_RELAY_DESCRIPTION[] PROGMEM = "Multi Relay";
 ```
 
-
-# Debugging
-In a `platformio.ini` file in section [common_env_data] you can uncomment (remove ";" at the beginning) some `build_flags`:
+### Network Configuration
+You can use network connection (Ethernet or WiFi) based on MySensors capabilities (ESP8266, ESP32, W5100, W5500, ENC28J60).
+This needs some additional configuration in `config.h`:
+* `#define MY_WIFI_SSID "<YOUR WIFI NAME>"` - WiFi SSID in case of ESP8266/ESP32
+* `#define MY_WIFI_PASSWORD "<YOUR WIFI PASSWORD>"` - WiFi password in case of ESP8266/ESP32
+* `#define MY_HOSTNAME "MULTI_RELAY_2"`
+* `#define MY_MAC_ADDRESS 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED`
+* In case of static IP address (no DHCP) you have to define following parameters:
+  * `#define MY_IP_ADDRESS 192,168,178,87` - IP address of the device
+  * `#define MY_IP_GATEWAY_ADDRESS 192,168,178,1` - IP address of your router
+  * `#define MY_IP_SUBNET_ADDRESS 255,255,255,0` - local network mask
+* `#define MY_PORT 5003` - if not using MQTT, MySensors gateway will listen on this port (if using default 5003 you dont need this in config.h)
+* `#define MY_USE_UDP` - if not using MQTT, you can choose UDP (default is TCP)
+
+This are still experimental options and waiting for contribution with working config.
+
+### MQTT Configuration
+* `#define MY_GATEWAY_MQTT_CLIENT` - enable MySensors MQTT support
+* `#define MY_MQTT_PUBLISH_TOPIC_PREFIX "multi-relay/out"` - gateway will send events to this topic
+* `#define MY_MQTT_SUBSCRIBE_TOPIC_PREFIX "multi-relay/in"` - gateway will listen for commands on this topic
+* `#define MY_MQTT_CLIENT_ID "multi-relay-2"` - client id when connecting to MQTT broker
+* `#define MY_CONTROLLER_IP_ADDRESS 192,168,178,17` - MQTT broker IP address
+* `#define MY_CONTROLLER_URL_ADDRESS "test.mosquitto.org"` - MQTT broker URL instead of ip address
+* `#define MY_PORT 1883` - MQTT broker port
+* `#define MY_MQTT_USER "<YOUR MQTT USERNAME>"` - user name, if your MQTT broker requires authentication
+* `#define MY_MQTT_PASSWORD "<YOUR MQTT PASSWORD>"` - user password, if your MQTT broker requires authentication
+* `#define MY_NODE_ID 1` - may be required (need tests)
+
+
+## Debugging
+In a `platformio.ini` file in section [env] you can uncomment (remove ";" at the beginning) some `build_flags`:
 * `DEBUG_STATS=1000` - time statistics can be printed on serial, when they are triggered via appropriate MySensors command - read more in MySensors commands sections
 * `DEBUG_COMMUNICATION` - show some debug information about received MySensors commands on serial
 * `DEBUG_ACTION` - detailed information about button actions on serial
 * `DEBUG_STARTUP` - detaled information about configuration parameters. Usefull when you want report some problems with sketch.
 
-
-# Expander
+## Expander
+Expanders alow you to have more GPIO pins over I2C protocol. On a single I2C data line you can connect one or more expanders.
+It is recomended to use expanders only for relays, because they are much slower than internal GPIO, and switches are checked all the time.
 Only one expander library at a time is supported.
+To build expander version just select appropriate `env` with sufix `pcf` or `mcp`.
 
-## PCF8574
-To use expander PCF8574 you have to install library:
-* download https://github.com/skywodd/pcf8574_arduino_library as zip archive
-* extract directory PCF8574 into `lib/PCF8574`
-Basic information about expander and library you can find here - https://youtu.be/JNmVREucfyc (PL, library in description)
-
-And in a `platformio.ini` file in section [common_env_data] uncomment `EXPANDER_PCF8574` in `build_flags`.
+### PCF8574
+Popular expander with additional 8 GPIO.
+* Library `https://github.com/skywodd/pcf8574_arduino_library`.
+  Basic information about expander and library you can find here - https://youtu.be/JNmVREucfyc (PL, library in description).
 
-## MCP23017
-https://github.com/adafruit/Adafruit-MCP23017-Arduino-Library
-
-In a `platformio.ini` file in section [common_env_data] uncomment expander library in `lib_deps_builtin`:
-```
-adafruit/Adafruit MCP23017 Arduino Library @ ^1.2.0
-```
-and `EXPANDER_MCP23017` in `build_flags`.
+### MCP23017
+Popular expander with additional 16 GPIO.
+* Library: https://github.com/adafruit/Adafruit-MCP23017-Arduino-Library
 
-## Configuration
 
+### Configuration
 Configure expander id in `config.h` file:
 ```
 const uint8_t gExpanderAddresses[] = {0x20}; //PCF8574
@@ -175,17 +243,20 @@ To simplify using expanders, there is "E(a,b)" macro:
 E(0,0) - first pin on first expander
 ```
 
-## Relay config example
+### Relay config example
 ```
 const RelayConfigDef gRelayConfig[] PROGMEM = {
-  {1, E(0,3), RELAY_TRIGGER_LOW, "RELAY 1"}
+  {1, E(0,3), RELAY_TRIGGER_LOW, -1, "RELAY 1"}
 };
 ```
 
-# Troubleshoting
-If you have problems with unstable relay or button states after startup, uncomment `IGNORE_BUTTONS_START_MS=2000` in your `platformio.ini`.
+## Troubleshoting
+1. If you have problems with unstable relay or button states after startup, uncomment `-D IGNORE_BUTTONS_START_MS=2000` in your `platformio.ini`.
+
+2. Relays randomly turn on/off on startup - one reason could be eeprom memory corruption (it has limited number of writes).
+As a solution you can change eeprom area with `EEPROM_OFFSET` build flag (i.e. `-D EEPROM_OFFSET=100`).
 
-# MySensors special commands
+## MySensors special commands
 Show debug stats
 ```
 0;255;1;0;24;1
@@ -215,3 +286,13 @@ Reset
 ```
 0;255;1;0;24;6
 ```
+
+Validate relays & eeprom state
+```
+0;255;1;0;24;7
+```
+
+Free Memory
+```
+0;255;1;0;24;8
+```

changelog

@@ -1,3 +1,15 @@
+# 2.4.0
+
+New features:
+- Dependent relays
+- Additional architectures: ESP8266, ESP32 (experimental)
+- Ethernet (LAN or MQTT) with W5100 or ENC28J60
+- Add multiple hardware combinations to platformio.ini so the user doesn't need to customize it so often
+
+Improvements:
+- Change button logic to be more independent from relays
+- Create wrapper for MySensors dependency so it can be better tested
+
 # 2.3.2 - Minor fixes
 - improve Virtual pins
 - typos fixes and revert remove "xstr" macro
@@ -16,6 +28,7 @@
 # 2.3.0 - Big architecture refactoring and new functionality - dependent relays
 New functionality:
 - Dependent relays and new configuration option "dependsOn"
+
 Technical changes:
 - Completely new software architecture to separate responsibility and add hardware abstraction for unit testing:
   - New class ButtonService
@@ -35,6 +48,7 @@ Technical changes:
 
 # 2.2.1 - Sensor reporting
 - reporting REED_SWITCH as S_DOOR in MySensors
+
 # 2.2.0
 - Without sending V_ARMED
 - Support MCP23017