Get your UniPi up and running
This is the easiest part. Head over to https://github.com/UniPiTechnology/evok and follow the installation instructions. One thing though, if the PiDome server is running on a different Raspberry Pi then the UniPi one, open up the evok.conf configuration file turn on CORS and restart evok.
Quick start
Important: Currently only one UniPi connection is supported!
The UniPi implementation in PiDome follows a plugin structure. This is for the preparation to be able to run more then one instance so you will be able to connect to multiple UniPi devices. In future releases of the server you will be able to connect to multiple UniPi devices.
Let’s begin
When you are logged in onto the server go to “Management > Plugins > Device plugins” click “Add plugin” and select the “UniPi” as shown in the first screenshot. The second screenshot shows the page which will appear after your selection. Give the plugin a name recognizable for you, a description (mostly what it is meant for), the ip address of the webserver/websocket of the UniPi and the port where this is available. Make sure it is the same as in the evok runtime configuration file
Now that the plugin has been added a connection to the UniPi is made. You will see that it is running in the list of plugins when the connection has been successful. Now, let’s add the UniPi device:
Go to “Management > Devices > Add/Remove/Settings” and click the button add device. You will be presented with a list of drivers which you can select from (remember, this is a device plugin, so it behaves like it is real local attached hardware). Select the “UniPi boards driver”, refer to the screenshot below:
When you have selected the UniPi driver you will be able to select the device you want to add so select “UniPi board”.
You will be presented with options for you to recognize the device, fill in the required fields and discard the address, just leave it null (this field is soon to be removed):
Click add device and you are done, you now have the UniPi device added to the server. When you go to “Control > Devices” you will be presented with your list of devices, or when you are a new user the PiDome server device and your UniPi. Click on the UniPi device and start switching to test if it works (If you have left everything default and the plugin is running it will) See the little clip below switching the UniPi’s (and an expansion board) relays using single buttons and macro’s
Adding UniPi extension boards
When you want to add the extension boards 8 relay board EMO-R8 or the 4 Relay/4 Digital input board 1Wire 4xSSR/R + 4xDI and you have left the default options in the evok.conf file you can just add these boards as these have already been configured. Just use “Add device” to add these.
If you have changed the configuration it is time for some extra attention.
Creating and adding extension board devices
If you are new to PiDome here is a short explanation: Within PiDome all devices have definitions. These definitions are used to compose the device visuals, device controls and datatypes. fortunately PiDome has a device editor in the web interface (so no hastle with configuration files). These device definitions are called skeletons. Most of the time you only have to create a skeleton once and is being re-used every time you add the same device type. A self created device is called a Custom device.
How are UniPi device skeletons setup
If you are already known with the device editor you can skip this part.
Intro
A device skeleton is a JSON structure with properties, i will not explain the structure but discuss the parts. It has a name, description, controls and address parts. There is also an options part but this is not used. To view a structure and create a device head over to “Maintenance > Devices > Custom devices”. You will be presented with a list of custom devices
Click for example on the edit button next to the EMO-R8 relay extension board (9-16/1-8) board. You will now be presented with the device editor showing the device name, description and controls. When you press on the “Show JSON” button you will be presented with the JSON format.
Device skeleton group and control relations
When you look below the above shown top section, you will be presented with the controls section. And this is the important part. A device’s control section is made up of groups and controls. A control is placed inside a group (you have no other choice). As you may, or have not noticed the evok API on the UniPi has specific identifications for devices which is done with a parameter called “dev” which consists of relay, ai,ao,input,temp,etc.. Next to this parameter there is also a circuit parameter which tells at what address the specific dev is located. PiDome uses the “dev” and “circuit” parameters to identify what kind of device it is and where it is located.
PiDome uses the group to map to the device types, and the location of the type is used by the controls. To map it:
- A device is a board
- A group is a collection/group of devices on this board (relays, digital inputs, etc..)
- A control is the relay, digital input, analog output, etc…
I use the tool Postman to make calls to RPC API’s, as the evok software contains a JSON-RPC api this tool is perfect to identify UniPi devices and their dev and circuit parameters. The first screenshot below shows you the relation between a group and device types. (PS to see the UniPi known devices point your browser or PostMan tohttp://your.unipi.ip.address/rest/all/ )
As you can see in this screenshot there is a group called Relays which contains all the relays. By having the group id called relay PiDome knows this group will contain relays. Press cancel to close.
The next screenshot shows you the relation between the circuit parameter and a PiDome control. I have added the evok.conf file to make it more clear.
As seen in the screenshot the control id of 9 identifies the specific relay in the device.
The above structure is maintained between all the device types. This means that every dev is placed in it’s own group, “temp” has it’s own group, “ai” has it’s own group, etc.
Quick FAQ:
- Is there a relation between a device skeleton in PiDome and an extension board?
No there is not. The reason for this is that the evok JSON-RPC api does not provide this. If you do the RPC call http://your.unipi.ip.address/rest/all/ you will see that everything is in one big list, so RPC wise it appears as one big device. - So why does PiDome has more device skeletons, even though they are examples?
It helps to identify where which relays and or inputs/outputs are. If you want you can create one massive super skeleton. - What does the clone button do?
It clones a device skeleton. If you have multiple of the same types, you can clone it and use the edit controls to change the group id (dev type) and control id’s (circuit address). - How to add/delete/edit groups and controls?
To add a group drag and drop it onto the Device Structure field, to edit a group click the groups wrench and to delete click the group’s red circle.
To add a control drag and drop it onto the group where you want to have it. To edit click the wrench and to delete click the red circle. - Tip:
When creating a new skeleton, use a descriptive name! For example I have added (9-16/1-8) to the EMO-R8 example device so i know it is circuit 9-16 which is mapped to relay 1-8. - Should i use the one-wire address (circuit) of an one-wire sensor as a control id?
Yes, and use the dev type as the group id and place that control inside that group.
Control definitions
Every device has a specific control type, a relay is a toggle button, analog outputs are ranged sliders, analog and digital inputs are data controls as well is the temp device. Please refer to the table below to see what belongs to what
| Dev type | Control type | Data type | Remarks |
|---|---|---|---|
| relay | Toggle button | String | Use 1 for on value and use 0 for off value |
| input | Data field | boolean | A high will be true, a low will be false |
| temp/1wdevice | Data field | float | No remarks |
| ai | Data field | float | No remarks |
| ao | Slider | float | This control should be ranged between 0 and 10 (Volt) |
The above table shows minimum requirements. We are still very busy with the device editor tools and it is possible in the future these selections are auto restricted. Keep in mind that the group id and the control id’s are also minimum requirements, refer to the above screenshots. Also make sure you group correctly.
Some last words
You do not need to define any options. These are only when you are coding a device for the server. You do not need the address field, please set this to “Not used”. We have reserved this feature for UniPi devices in the future where it will be possible to define just one control where the address field is used to identify it. So do not use it (yet)
The above reflects on the current release at time of writing. I’m planning additional features like device discovery (this helps you to identify new devices on the bus) and single control devices. If you have any questions post them in the Hardware section of the PiDome forum. There is also a PiDome section on the UniPi forum where i will also be regularly looking.
Have fun with PiDome and UniPi!
