Souliss is a networking framework for Arduino and compatibles boards, and is designed to let you easily build a smart home that is distributed over multiple boards via Ethernet, wireless point-to-point and RS485 bus.

Souliss is an open-source and community driven project, you can use the wiki and Community to get help and share you results. Additional details and examples are available on the openHAB example wiki page.

The binding requires a deployed network. As a minimum, you need one Souliss node with Ethernet access configured as a Gateway. A Gateway is a special node that is able to communicate with the user interfaces. The binding interacts as a user interface for Souliss.

A starting point is the Souliss wiki. The best is to start with a single node and connect with SoulissApp. The code for networking activities of this binding is based on SoulissApp code, so once connected with SoulissApp, you can move to openHAB directly.

You can use SoulissApp and the Souliss binding at the same time, and generally up to five (by default, but can be increased) user interfaces simultaneously.

The easiest way is start with a simple example to control an ON/OFF light (though a relay). In this section, we show you the code to upload on your Arduino with Ethernet shield (based on W5100 / W5200) or an ESP8266 as SoC and the configuration of your openHAB. The next section will explain the details.

Use the following sketch on your Arduino, before compile ensure that you have installed the Souliss framework from the [[Library Manager | http://www.arduino.cc/en/guide/libraries]], just search for souliss inside the Library Manager and select Install.

You need to change the IP address inside the sketch according to one free IP address in your network.

/**************************************************************************
Souliss - Hello World
This is the basic example, control one LED via a push-button or Android
using SoulissApp (get it from Play Store).
Run this code on one of the following boards:
- Arduino with W5100 Ethernet Shield
***************************************************************************/// Configure the framework#include"bconf/StandardArduino.h"#include"conf/ethW5100.h"#include"conf/Gateway.h"/*
If you are using W5200 or ENC28J60, you just need to change
the #include "conf/ethW5100.h" with #include "conf/ethW5200.h"
or #include "conf/ethENC28J60.h"
This assume that your SPI Chip Select (CS) is on pin 10 as in
most of the Ethernet shield.
*/// Include framework code and libraries#include<SPI.h>#include"Souliss.h"// This identify the number of the LED logic#define MYLEDLOGIC 0 // Define the network configuration according // to your router settings
uint8_t ip_address[4]={192,168,1,77};
uint8_t subnet_mask[4]={255,255,255,0};
uint8_t ip_gateway[4]={192,168,1,1};#define Gateway_address 77#define myvNet_address ip_address[3] #define myvNet_subnet 0xFF00#define myvNet_supern Gateway_addressvoidsetup(){Initialize();// Set network parametersSouliss_SetIPAddress(ip_address, subnet_mask, ip_gateway);SetAsGateway(myvNet_address);// Define a simple LED light logicSet_SimpleLight(MYLEDLOGIC);// We connect a pushbutton between 5V and pin2 with a // pulldown resistor between pin2 and GND, the LED is // connected to pin9 with a resistor to limit the // current amountpinMode(2, INPUT);// Hardware pulldown requiredpinMode(9, OUTPUT);// Power the LED}voidloop(){// Here we start to playEXECUTEFAST(){UPDATEFAST();// We process the logic and relevant input // and output every 50 millisecondsFAST_50ms(){// Use the pin2 as ON/OFF toggle commandDigIn(2, Souliss_T1n_ToggleCmd, MYLEDLOGIC);// Drive the LED as per commandLogic_SimpleLight(MYLEDLOGIC);// Use the pin9 to give power to the LED according to the logicDigOut(9, Souliss_T1n_Coil, MYLEDLOGIC);}// Here we handle here the communicationFAST_GatewayComms();}}

In this case we use the ESP8266 as a SoC and not simply as a transceiver, so Souliss is loaded directly on the module and doesn't require any other microcontroller. You need to install the ESP8266 cores in your Arduino IDE.

Compared to the previous example, you only need to change the configuration files to specify that you are now using an ESP8266 and the relevant WiFi library.

/**************************************************************************
Souliss - Hello World
This is the basic example, control one LED via a push-button or Android
using SoulissApp (get it from Play Store).
Run this code on ESP8266 as WiFi SoC.
***************************************************************************/// Configure the framework#include"bconf/MCU_ESP8266.h"#include"conf/Gateway.h"#include"conf/IPBroadcast.h"// **** Define the WiFi name and password ****#define WIFICONF_INSKETCH#define WiFi_SSID "mywifi"#define WiFi_Password "mypassword" // Include framework code and libraries#include<ESP8266WiFi.h>#include"Souliss.h"// This identify the number of the LED logic#define MYLEDLOGIC 0 // Define the network configuration according // to your router settings
uint8_t ip_address[4]={192,168,1,77};
uint8_t subnet_mask[4]={255,255,255,0};
uint8_t ip_gateway[4]={192,168,1,1};#define Gateway_address 77#define myvNet_address ip_address[3] #define myvNet_subnet 0xFF00#define myvNet_supern Gateway_address// **** Define here the right pin for your ESP module **** #define OUTPUTPIN 5voidsetup(){Initialize();// Set network parametersSouliss_SetIPAddress(ip_address, subnet_mask, ip_gateway);SetAsGateway(myvNet_address);// Define a simple LED light logicSet_SimpleLight(MYLEDLOGIC);pinMode(OUTPUTPIN, OUTPUT);// Power the LED}voidloop(){// Here we start to playEXECUTEFAST(){UPDATEFAST();// We process the logic and relevant input // and output every 50 millisecondsFAST_50ms(){// Drive the LED as per commandLogic_SimpleLight(MYLEDLOGIC);DigOut(OUTPUTPIN, Souliss_T1n_Coil, MYLEDLOGIC);}// Here we handle here the communicationFAST_GatewayComms();}}

Of course you have to care about the PIN addressing that is different on ESP8266 compared to an Arduino board.

index of the binding between 1 - 100. Please ensure that each user interface (SoulissApp, openHAB, ...) has a different USER_INDEX and NODE_NUMBER. Those values are used to identify the interface. You can get the values used by SoulissApp from the Networking menu.

NODE_INDEX

Yes

node of the binding between 1 - 254. Please ensure that each user interface (SoulissApp, openHAB, ...) has a different USER_INDEX and NODE_NUMBER. Those values are used to identify the interface. You can get the values used by SoulissApp from the Networking menu.

<Typical> is one of predefined logic dedicated to smart home devices like lights, heating or antitheft. <Typical> can be one of T11, T12, T13, T14, T16, T18, T1A, T22, T51, T52, T53, T57. <Typical>s are defined here. Typicals match directly with openHAB items. This defines the interaction between the user interface in openHAB (same is for SoulissApp) and the action executed by the node.

<nodeID> is the ID of the node. The first node listed in your SoulissApp has <nodeID> 1. Increase for your further nodes. Can be in the range 1 - 254.

<slot> is the slot where your <Typical> is located. This is defined in the sketch loaded in your node. Can be in the range 1 - 254.

sections in [square brackets] are optional

<bit> is used only for <Typical>s that work bitwise, as T1A. Can be in the range 1 - 8.

In order to track the health and timestamps, two service <Typical>s has been introduced: D98 (Health) and D99 (Timestamp). Those are not defined in Souliss sketches and are only available in the binding.