17/6/20 Introducing the first article of a blog series focused on using open-source tools in Unipi controllers
This new series aims primarily at students, developers, DIY enthusiasts and fans of Raspberry Pi or other similar platforms. It can be however useful also for users already acquainted with Unipi PLCs that wish to try out an alternative to the officially supported Mervis software. Either way, the articles assume some level of programming knowledge - the reader should possess at least basic knowledge of working with Linux shell command prompt and should know the terms IP address, flash memory, SSH or Modbus.
In this article we will:
- create an SD card with a pre-assembled operating system (OS) image
- slightly modify a pre-assembled Hello world program
- explain the inner software structure of Unipi controllers
All examples will be showcased on a Neuron-line controller, namely the Unipi Neuron M203. The following guide can be, of course, applied to other Unipi controllers as well, as the software for all of them is based on Linux OS, specifically its Debian distribution.
Neuron M203 introduction
Unipi M203 sketch
| Features | ||
| Digital inputs | 20 |
Raspberry Pi 3 Model B |
| Digital outputs | 4 | |
| Relay outputs | 14 | |
| Analog inputs | 1 | |
| Analog outputs | 1 | |
| RS485 interface | 1 | |
| 1-Wire bus | 1 | |
Creating a microSD with an OS image
Neuron controllers are based on the Raspberry Pi single-board computer which does not feature any internal flash memory to store an operating system. For that reason, we need to create a boot microSD card first, which we will then insert into the controller. Aside from the OS image, the card will contain all necessary tools and applications including your user data. Let's get to it.
For this phase we will need the following:
- Any computer equipped with a (micro)SD card slot and any suitable operating system - to honour the series name this tutorial utilizes the Linux OS, specifically Mint distribution (of course, other distros can be used either as native OS or in a virtual environment - e.g. VirtualBox for OS Windows). You can also use the Raspberry Pi computer with an external USB card reader
- a microSD card (minimal capacity is 4GB, we recommend a memory of 8GB or more)
- The M203 controller itself
For both main Unipi platforms (Neuron and Axon) you can currently choose from three pre-assembled OS images:
- Mervis OS - an OS image for Mervis - the main supported software solution for Unipi PLCs. You can learn more about Mervis on this link.
- OpenSource OS - a clean Debian-based operating system with all tools and drivers needed to communicate with the controller's I/Os. Serves as a basis for installing third-party solutions or for custom development. SSH access is enabled by default, the user has root-level access.
- Node-RED OS - identical to the Open-source OS, but also contains the pre-installed Node-RED platform including all necessary supplemental tools (ie. EVOK - see below). This tutorial utilizes this option.
You can download the current version of all above-mentioned OS images on Unipi Knowledge Base. Extract the downloaded ZIP archive and burn it to the connected microSD card using an appropriate tool (ie. dd tool). The operation itself can take several minutes. The entire process can look like the following (with different names of files and directories, of course):
martyy@martyy-pc:~#wget https://kb.unipi.technology/_media/files:software:os-images:neuron-node-red_image-20200507.2.zip
martyy@martyy-pc:~#unzip files\:software\:os-images\:neuron-node-red_image-20200507.2.zip
martyy@martyy-pc:~#dd if=neuron-node-red_image-20200507.2.img of=/dev/sda bs=1024 status=progress && sync
1907815424 bytes (1.9 GB, 1.8 GiB) copied, 547 s, 3.5 MB/s
1863680+0 records in
1863680+0 records out
1908408320 bytes (1.9 GB, 1.8 GiB) copied, 576.53 s, 3.3 MB/s
martyy@martyy-pc:~#
Insert the prepared card into the unpowered controller. With the card inserted, plug in the controller's 24V power supply. A successful OS boot is indicated by blinking of LEDs next to the RJ45 connector.
Connecting to the controller
By default, the software interface is set to dynamic IP assignment using the DHPC protocol. Connecting to the PLC thus requires to detect its IP address first. You can do so in multiple ways - using an IP address scanner, using a list of addresses provided by your router, or via the mDNS service enabled by the Avahi daemon (avahi-resolve is included in the avahi-utils Debian package).
All Unipi controllers use a hostname in <model>-sn<serial number> format, such as:
martyy@martyy-pc:/home/martyy# avahi-resolve -n M203-sn55.local
M203-sn55.local 192.168.221.145
Upon entering the detected IP address into your browser the following screen should appear, showing the opening page of EVOK:
The address is set, so let's sum up everything that runs on the controller and is accessible:
- SSH on standard port 22 (login: unipi, password: unipi.technology)
- several webpages:
- Port 80 - EVOK web panel (see below) for a quick check of the functionality of all inputs/outputs, or to change their mode (we will elaborate on this further in the future articles of this series)
- Port 1880 - the main interface of Node-RED, used to create visualisations (GUI Dashboard) and the program logic itself
- Port 1880/ui - a graphic interface (GUI) coupled to the control program
First program
In Node-RED, you can create so-called event-driven applications triggered by certain events. These events (triggers) can take from of both physical events (eg. HW-related, such as binary input state change) and software events (time switch impulse, calculated time of dusk etc). A word "flow" is then used to describe the flow of the event through the network of interconnected nodes which can react to it. "Flow" is also used to describe a group of interconnected nodes. A single Node-RED project can contain multiple such flows.
Node-RED contains a simple demonstration program by default, called Hello World. This program allows you to monitor and control some inputs/outputs on the controller and also contains a simple visualisation tool - GUI Dashboard.
If you click on any switch in the Digital outputs section, the corresponding digital output should change its state, eg. its LED should power up. If the LED is on, everything is ready and we can try to modify the program a little. Here, you can freely experiment with the built-in nodes, or you can easily import more nodes downloaded from the internet (Manage palette -> Install).
The simple example mentioned above adds a new control element (button) to the dashboard. This button switches the DO1.1 output with a 5-second delay.
After each modification of the program, you need to "deploy" it. You can do so by clicking on the below-mentioned Deploy button located at the upper right corner of your screen.
This blog article series is not intended to be a fully-fledged Node-RED tutorial. For further study of this powerful tool we can recommend the following resources:
- Official tutorials available at https://nodered.org/docs/tutorials/
- Guide series at http://noderedguide.com/
- A multitude of tutorials on YouTube, such as this one
Internal SW structure
A schematic of Unipi PLC internal SW structure
If you reached this part of the article and you have a little bit of curiosity, chances are you are probably wondering how Unipi controllers work software-wise. Due to the software openness of Unipi controllers, there is no secret and you can see for yourself using the SSH login. There are three key processes important to run user applications:
- unipi_tcp_server - a service providing access to peripherals (controller I/Os) via the Modbus TCP protocol. Designed primarily for other services/processes running on the controller, but can be also configured for direct access "from the outside" - we will try this in one of the future articles. This process is dependent on the kernel module (named "unipi") which provides access to the SPI physical bus to which most of I/Os is connected.
- EVOK - a tool to access TCP Modbus server functions through a set of web services (WebSocket, REST, SOAP, RPC,...). It has the role of a necessary communication "bridge" between TCP Modbus server and Node-RED (in this case WebSocket is used for communication).
- Node-RED - a user-friendly environment to design control logic (Flow) and create visualisations (Dashboard). The software runs in a web browser window, its main programming language is JavaScript
Within the OS a set of support utilities is also included, providing common services such as DHCP client, SSH server, cron, avahi-daemon etc.
Conclusion
In this article we created an operating system image for our Unipi controller, containing important tools to access the controller's peripherals. The image also contains the pre-installed Node-RED software to design a control logic (program) and web visualisations (GUI), which comes with a simple demonstration project. We used this project to describe the process of designing a program using an event-based approach (so-called "flow").
In the next article, we will focus on the integration of more interesting peripherals, such as thermometers. We will also try to create a more sophisticated program in Node-RED, using it to demonstrate the basics of debugging in case something does not work to our liking.
