search

DanielOgorchock / OmniThing

OmniThing turns your ESP32, ESP8266, Raspberry Pi, Linux Computer, or Windows Computer into a SmartThings composite Device. It is being developed as a cross-platform successor to ST_Anything.
GNU General Public License v3.0
64 stars 16 forks source link

readme

OmniThing

A cross-platform successor to ST_Anything

ESP8266, ESP32, Raspberry Pi, Linux, Windows

OmniThing allows you to integrate your computer or microcontroller with SmartThings. Changing functionality is as simple as editing a json configuration file. Take a look at this README to learn how to get started.

Check out the OmniThing Website. It is home to a configuration tool that makes setting up OmniThing much easier.

State of the Project

OmniThing is currently in Alpha. Please keep in mind that at the time of writing this it has only been used by one person, so any bug reports are appreciated.

Contributions to the project are encouraged. A guide to contributing can be found toward the bottom of this README.

People trying out OmniThing coming from ST_Anything may note that fewer Arduino devices are supported. This is due to memory restraints. OmniThing uses much more RAM than ST_Anything due to it using a json configuration. Due to this, OmniThing is not a total replacement of ST_Anything functionality, so people using Arduino Unos and Megas won't have much luck with OmniThing (Mega support could potentially come in the future, but Uno has no chance).

Additionally, OmniThing is still in early development, so it may be less stable than ST_Anything in addition to missing some of the ST_Anything device types at this time.

Finally, unlike ST_Anything, OmniThing does not require the end user to edit actual source code. Instead of adding stuff to an Arduino sketch, everything is done through the OmniThing json configuration file. OmniThing parses this file and dynamically creates the desired devices at startup.

Goals for Beta:

Version History

Alpha

Design

The goal of OmniThing to to create a modular home automation device solution for several platforms. OmniThing currently supports ESP8266, ESP32, Raspberry Pi, Linux computers, and Windows computers. It is possible that other embedded Linux platforms will be supported in the future (i.e. Beaglebone).

One of the biggest limitations of the ST_Anything library is that its devices are rather rigid, not giving users a simple way to combine capabilities without needing to create custom classes. Furthermore, it has little to no concept of sensors with the same capability. Capabilities are to be a major focus of the OmniThing library.

An example of the potential benefits of using a capability-based architecture can be seen in the following hypothetical device: an auto-irrigation controller. Such a device would need to collect soil moisture readings and react accordingly by opening a water valve when the soil is too dry. There are myriad moisture sensors, and likely even more ways to control the flow of water. With capabilities, the auto-irrigation controller could simply be composed of a numerical value reader (to get moisture levels) and an actuator (to provide water flow). The specifics of what components are being used are abstracted, making the irrigation device far more flexible out of the box.

OmniThing is configured entirely through editing a json file. Example configurations can be found in the example_configs directory of this repository. This README includes documentation on all the possible parameters for the config file.

Devices

Devices correspond to actual SmartThings devices (they will show up in the phone app).

OmniThing is designed to make the Devices as generic as possible. A Switch device knows nothing about GPIO pins. Instead, its configuration requires it be given an OutputBool. It doesn't care if that OutputBool is a GPIO output or something that runs a shell script to turn off a web server. In this way, the framework is very flexible to the specific needs of the user.

Composite Peripherals

Composite Peripherals provide interfaces to sensors/actuators that are composed of multiple attributes. A perfect example is a DHT22, which provides both temperature and humidity. A TemperatureMeasurement device can reference the temperature attribute of a DHT22 Composite Peripheral. A RelativeHumidityMeasurement can do likewise with humidity.

Network Receivers

Network Receivers are how OmniThing receives HTTP messages from the hub. Typically this is where you specify things like the port and ip to have the HTTP server listen on.

NOTE: Make sure that the OmniThing device's IP is static. You can typically do this in your router's DHCP server configuration.

Network Senders

Network Senders are how OmniThing sends HTTP messages to a home automation platform (i.e. SmartThings, Hubitat). Typically this will require you to specify an ip address and port for the hub.

NOTE: Make sure that your hub's IP is static. You can typically do this in your router's DHCP server configuration.

Input Value Types

The following list shows the current input value types.

Output Value Types

The following list shows the current output value types.

SmartThings Setup

NOTE: Right now these instructions are basically ripped directly from ST_Anything, so the pictures are slightly wrong.

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.

Adding a New OmniThing Device

Your screen should look like the following image (but with omni_parent, not PARENT_ST_ANYTHING_ETHERNET):

screenshot

Your screen should look like the following image:

screenshot

Hubitat Setup

TODO: Actually make the parent device handler support Hubitat

Installation Instructions

OmniThing is easy to install on raspberry pi, linux platforms, and arduino platforms.

Arduino (ESP8266/ESP32)

Just use the OmniThing website. The configuration tool allows you to download a ready-to-build arduino sketch.

Raspberry Pi

It is easy to install OmniThing on a Raspberry Pi and keep it updated. You can directly use the apt package manager like you would for any other raspbian package. You just need to add the OmniThing repository.

Add the OmniThing repository

sudo sh -c 'echo "deb http://omnithing.net/repository/rpi ./" >> /etc/apt/sources.list'

Add the omnithing gpg key

curl http://omnithing.net/repository/rpi/KEY.gpg | sudo apt-key add

Install the omnithing package

sudo apt-get update && sudo apt-get install omnithing

Updating OmniThing

If a new version of OmniThing is released, you can update to it with the command below:
sudo apt-get update && sudo apt-get upgrade

Editing Configuration

You can edit the current OmniThing configuration using the self-hosted webserver running on port 3333. In your web browser, navigate to http://replace_with_your_pi_ip:3333

Other Linux Platforms

Building and Installing

cd
git clone https://github.com/DanielOgorchock/OmniThing.git
cd OmniThing
cmake . -DBUILD_TARGET=linux -DWEB_CONFIG=webpage/config_linux.json
sudo make install

Starting Services

sudo systemctl enable omnithing
sudo systemctl enable omnithing-webserver
sudo systemctl start omnithing
sudo systemctl start omnithing-webserver

Editing Configuration

You can edit the current OmniThing configuration using the self-hosted webserver running on port 3333.

Build Instructions

The build instructions can be ignored for linux, raspberry pi, and arduino platforms if you only want to use OmniThing. They are only needed if you want to directly edit OmniThing source code. Refer to the installation instructions for those platforms if you don't need to edit source files.

Prerequisites

Now, clone this repository and follow the proper instructions below for your target platform.

git clone https://github.com/DanielOgorchock/OmniThing.git

Arduino (ESP8266/ESP32)

Raspberry Pi

Linux Computer

Windows Computer

Board Pinouts

Reference the images below to determine which pin numbers to use for your board. Note: Use the numbers following the "GPIO" labels for the ESPs, not the absolute pin position.

ESP8266

alt text

ESP32

alt text

Raspberry Pi

Be sure to pay attention to whether you have a raspberry pi with 26 or 40 pins. alt text alt text

Json Parameter Documentation

It is recommended that you create your json configuration with the web-based tool found at omnithing.net. There's no need to edit any text files yourself unless you really want to.

Below is the documentation for everything configured in the json file.

If you have never used json before, don't worry. It's pretty simple. Take a look here to see how the format works.

Empty Json File

This is the barebones framework for the config file.

Example configuration files can be found in the example_configs directory.

{
    "NetworkReceiver": {

    },

    "NetworkSender": {

    },

    "CompositePeriphs": [

    ],

    "Devices": [

    ]
}

Shared Device Parameters

Every Device (NOTE: just the devices, not the various inputs/outputs, composites, etc) below also have the following parameters.

Name

Triggers

Subscriptions

The "poll" command

Parameter Documentation

Click here to see all the supported parameters, commands, and events. Use this as a reference when editing your configuration file.

Contributing to OmniThing

NOTE: Before you read further, I apologize to the current state of documentation within the project's source files (as in, there basically is none). Hopefully it will be improved in the future. At least the directory structure is fairly straight-forward.

OmniThing's modularity makes it pretty easy to add funcionality. If you intend to add something to OmniThing, it is important to keep a few things in mind:

Only Add Devices if Required

Say you are intending to add support for a new temperature sensor. It may be tempting to create a new Device. This is a bad idea. Devices are meant to be very generic. Instead, a temperature sensor could be implemented as an InputFloat, which would allow the existing TemperatureMeasurement device to utilize it.

Put the Code in the Proper Folder

OmniThing's directory layout is organized based on platform.

Use Abstractions when Possible

Try to avoid using platform specific code. OmniThing has many abstractions to aid with this.

Also, try not to use String classes unless your code is only ever intended to work on a particular platform. If you want it to run on everything, use good old c strings.

Update Config

Add your new Device/CompositePeriph/Input/Output/etc to the appropriate json file in the config directory.

Follow Device Naming Scheme

If your are adding a device (Note: Device, not input/output/compositePeriph) that pretty directly corresponds to a capability in the SmartThings documentation, please name it after its name there (just like the rest of the current devices).

Avoid Dynamic Memory Allocation

Since OmniThing runs on embedded systems, limit dynamic memory allocation to initialization only if possible (for example: when parsing json configuration). This makes OmniThing stable and less prone to memory leaks and heap fragmentation.

Adding Support for a New Platform

The following is a general checklist for adding a new platform to OmniThing.

OmniThing uses very little platform-dependent code, so there are only a handful of things that need to be implemented for a new platform.

Linux-based

This should be pretty easy. All that really needs to be implemented is the GPIO related stuff (digital input, digital output, analog input, pwm output, servo, etc.), which is nicely abstracted for the most part. Take a look in the raspberry_pi code to see how to add support for GPIO.

Other