DanielOgorchock / ST_Anything

ST_Anything is an Arduino library, sketch, and Device Type that works with your SmartThings ThingShield to create an all-in-one SmartThings device.
GNU General Public License v3.0
438 stars 448 forks source link

ST_Anything v2.9.9

WARNING - SmartThings Web IDE GitHub integration is not available in all countries around the globe.

NOTE - ST_Anything v2.9.9 was tested using Arduino IDE 1.8.16 + ESP8266 v3.0.2

NOTE - ST_Anything v2.9.9 was tested using Arduino IDE 1.8.16 + ESP32 v2.0.3

Recent History:

Architecture Flow Chart

screenshot

Note: ST_Anything v2.9.9 was built using the Arduino IDE v1.8.16. Please make sure to upgrade your IDE.

Turn your Arduino UNO/MEGA/MKR1000/MKR1010/NANO33IoT, ESP8266, or ESP32 into Anything you can imagine! ST_Anything is an Arduino library, sketch, and Device Handlers that works with your hardware to create an all-in-one SmartThings device.

THIS DOCUMENT IS A WORK IN PROGRESS! The essential code is all here and has been tested. Documentation is still lacking somewhat, so feel free to submit a pull request to improve this ReadMe as you try to get things working.

New v2.6+ Parent / Child Devices screenshot

This package currently implements the following SmartThings Device Capabilities:

Note: Attempting to use all of these at once on an Arduino UNO R3 is likely to result in running out of SRAM on the UNO (the UNO only has 2 kilobytes of RAM.) Using an Arduino MEGA 2560 with 8 kilobytes of SRAM is recommended if you want to run everything at once. The ESP8266, ESP32, and MKR1000, MKR1010, NANO33IoT platforms also have a lot more memory available.

Overview

ST_Anything consists of four main parts:

Pre-Requisites for using LAN-to-HUB Ethernet connectivity (Arduino/W5100, Arduino/W5500, Arduino/ESP-01, NodeMCU ESP8266, ESP-01, ESP32, MKR1000, MKR1010, NANO33IoT)

Arduino IDE Setup Instructions

NOTE: Arduino IDE v1.8.9 + v2.5.2 ESP8266 Board Manager package for the Arduino IDE appears to have corrected the earlier memory leak. Please use this combination of software which has been successfully tested.

WARNING: If you are using an Arduino UNO, you may need to comment out some of the devices in the sketch (both in the global variable declaration section as well as the setup() function) due to the UNO's limited 2 kilobytes of SRAM. Failing to do so will most likely result in unpredictable behavior. The Arduino MEGA 2560 has 8k of SRAM and has four Hardware Serial ports (UARTs). If you plan on using many devices, get an Arduino MEGA 2560, a MKR1000, a MKR1010, a NANO33IoT, a NodeMCU v1.0 ESP8266-12e, or a ESP32 board.

SmartThings IDE Setup Instructions

Note: If desired, you can still create all of the Device Handlers manually by copying and pasting code from the GitHub repository files into your ST IDE. Trust me, the Github integration in SmartThings is so much easier! And, you will know when new versions of the DHs are available based on the color of each DH in your list of Device Handlers in the IDE.

SmartThings Device Handler Instructions - FOR USE WITH LAN-to-HUB WiFi/Cat5 Ethernet Devices

Your screen should look like the following image:

screenshot

Note: If you visit the "Recently" page of your Parent Device in your ST App on your phone, you may get an annoying warning that the setup is not complete. If you've entered all of the required data above, you can safely ignore this message. Once it scrolls off the 'Recently' list, the pop-ups will stop.

Your screen should look like the following image:

screenshot

SmartThings Device Handler Instructions - FOR USE WITH A THINGSHIELD

Items To Be Aware Of (regardless of whether using LAN or ThingShield)

1) Please do not start changing any code before getting one of the examples up and running on both the Arduino/ESP8266/ESP32 and the Device Handlers. It is always best to start with known working code before editing it. This greatly reduces the amount of troubleshooting later.

2) I have moved away from the old SmartApp Multiplexer + Virtual Devices with the v2.5 release of ST_Anything. I believe the ST Composite Device Handler architecture is far superior and much simpler for all users.

3) The names of the devices you create in the Arduino setup() routine MUST MATCH EXACTLY the names the Parent Device Handler code expects. The names are CaSe SenSiTiVe! Do not get creative with naming in the Arduino sketch as the Child Devices will not be created. Follow the naming convention as seen in the "ST_Anything_Multiples_xxxx.ino" sketches

4) If you are using a W5100 Ethernet Shield with an Arduino, the MAC address must start with '06' in order to be sure you're using a locally administered unicast MAC address. Make sure that you have unique MAC addresses if you use more than one W5100 on your network.

5) When entering the MAC address into the Device Preferences in your phone's SmartThings App, please be sure to enter it without delimiters (i.e. NO COLONS!), and in UPPERCASE. It should be in the form '06AB02CD03EF' without the quotes. The MAC address will be printed out in the Arduino IDE Serial Monitor window (115200 baud) when the board is restarted.

6) When using a NodeMCU ESP8266 board, you need to be aware of some GPIO limitations. I have assembled my findings in this image: screenshot

7) When using a ESP32 board, you need to be aware of some GPIO limitations

8) Button Devices - "where do they show up?" Buttons show up in the SmartApps that use them. The Aeon Minimote Device Handler, for example, has one tile with a remote control icon on it. Nothing else. It also has zero configuration options as well. I used this as a model for adding "Button" capabilities to ST_Anything per a user request. When you define the number of buttons (via the gear-based configuration menu in the parent DH) you are announcing to all SmartApps the number of buttons defined. This in turn allows SmartApps like "Smart Lighting", "CoRE", and "WebCoRE" to know how many "buttons" to offer you to configure an action. So, the easiest test is to create a new "Smart Lighting" automation, where you define the action to be based on a button "pushed" or "held" event from the Parent Device (no child devices are created for buttons). Give it a try! I have used this successfully in the past for testing purposes.

Final Notes for now...

Please refer to the header files of the ST_Anything library for explanation of specific classes, constructor arguments, etc... ST_Anything devices support inverted logic, default power-on states, debounce logic, etc... Read through the top section of the .h files found on the libraries\ST_Anything... folders for more information!

Look at the documentation in the 'ST_Anything_Multiples_xxxx.ino' files for explanation and examples of the general use of the library.

Older History of releases

Note: The ST_Anything v1.6 release was created on 2017-02-11 to make sure everyone can still get back to the original ThingShield-only code if necessary.
Note: If you want the old ST_Anything v2.2 code, please pull it by the v2.2 release number and follow the old v2.2 ReadMe

v2.0 Note: There are some significant changes as compared to the old v1.x platform. A signiciant rewrite of the "SmartThings" Arduino library was completed to incorporate Ethernet communications support. To use ST_Anything v2.x, you must also use all of the other supporting libraries found in this GitHub repository. Included is a the new SmartThings v2.x Arduino library which can be used standalone (examples are included in the library), or in conjunction with the ST_Anything library. v2.6 Note: Version 2.6 builds upon the changes in v2.x to incorporate SmartThings new Composite Device Handler (DH). This new functionality allows one Parent DH to create many Child Devices (using Child DHs). This allows more than one of each SmartThings capability per Arduino. Previously, this was only possible through the use of a Multiplexer SmartApp and virtual devices. The only manual device that has to be create within the ST IDE is the Parent. The ST_Anything Parent DH has been written to automagically create Child Devices that exist, or are added to, the Arduino ST_Anything sketch.