====== Attaching 1-Wire devices ======
In this tutorial, we are going to demonstrate, how to connect [[https://www.unipi.technology/1-wire-temperature-sensor-p63?categoryId=3|1-Wire temperature sensor]] and create very simple temperature regulator.
;;#
Patron \\
Neuron \\
Unipi 1.1 \\
Axon
;;#
Prerequisites:
* Unipi controller running Mervis OS
* Basic project in Mervis IDE in **Full mode** with
* attached controller
* created ModbusTCP channel with the Unipi controller device
* defined **Executable project** with one program
* setted **Autogen** on the Unipi controller device
* defined task running a program from **Executable project**
* successfully executed **Build**
* [[https://www.unipi.technology/power-supplies-c15|24 V⎓ power supply]]
* [[https://www.unipi.technology/1-wire-temperature-sensor-p63?categoryId=3|1-Wire temperature sensor]]
In this tutorial, we will use [[https://www.unipi.technology/neuron-c2|Unipi Neuron L503]].
===== Attaching 1-Wire temperature sensor =====
You can find all the informations about how to connect the DS18B20 based temeperature sensor [[en:automation:02-glossary:1wire-hidden|here]].
===== Configuring 1-Wire bus in Mervis =====
Let's assume your Mervis IDE workspace looks like this:
{{ :en:sw:01-mervis:attaching-1-wire-devices-01-basic-project.png?direct |}}
Right click on the **PLC** in the **Solution** tab of the **Left panel**. Click on the **Add channel** option.
{{ :en:sw:01-mervis:attaching-1-wire-devices-02-add-channel.png?direct |}}
New channel called **channel** will appear under the PLC. It is hightlighted, so in the **Properties** panel, you can see its properties. First, change the name of the channel to something more descriptive, in this example **1wire**.
{{ :en:sw:01-mervis:attaching-1-wire-devices-02-set-channel-name.png?direct |}}
Second parameter we need to change is the protocol. The 1-Wire protocol is "hidden" in the **PlatformIO** option of the **Protocol** dropdown menu.
{{ :en:sw:01-mervis:attaching-1-wire-devices-04-set-channel-protocol.png?direct |}}
And select the **OneWire** link protocol from the corresponding dropdown menu.
{{ :en:sw:01-mervis:attaching-1-wire-devices-04-set-channel-link-protocol.png?direct |}}
You now need to **deploy the solution** into the PLC to create the **OneWire** communication channel on it.
===== Detecting 1-Wire sensors =====
1-Wire bus is a serial bus, which can interconnect many sensors. Each sensor has its unique HW address, through which the master of the bus addresses the slave and reads data from. Therefor we need to tell Unipi controller to look for a certain devices on the bus. Luckily, we can detect all the sensors on the bus and then select the ones we are interested in.
To detect the sensors, right click on the **1wire** channel name under the PLC in the **Solution** tab of the **Left panel**. In the context menu, click on the **Detect One Wire Sensors**.
{{ :en:sw:01-mervis:attaching-1-wire-devices-06-detect-one-wire-sensors.png?direct |}}
To run the detection, the controller has to be in the **Commissioning mode**. The Mervis IDE will warn you and will set the mode for the detection and after detection change the mode of the controller back. Just confirm the warning by clicking on **Next >**.
{{ :en:sw:01-mervis:attaching-1-wire-devices-07-switching-to-commissioning-mode.png?direct |}}
If you follow this tutorial precisely, the Mervis IDE will show an error that the **Selected channel does not exist in the PLC**.
When you define new channel, the Mervis IDE will not be able to work with it, until you **Deploy** the solution to the PLC
**Deploy** the solution and run the detection again. The dialog **Detect OneWire Sensors** will appear and should contain a sensor you just connected. If you have more sensors, you should see all of them. To import the sensor into the **Solution**, tick the **Import** checkbox and click on **Next >**
{{ :en:sw:01-mervis:attaching-1-wire-devices-09-selecting-sensors.png?direct |}}
The importing of the sensor will proceed and finish with restoring the PLC's mode.
{{ :en:sw:01-mervis:attaching-1-wire-devices-10-restoring-previous-state.png?direct |}}
Since we added new device, we need to **Set autogen** to have the temperature variables available in the program. You should already know the drill - Right click on the sensor name -> **Set Autogen** and confirm the dialog by clicking **OK**.
{{ :en:sw:01-mervis:attaching-1-wire-devices-11-set-autogen.png?direct |}}
{{ :en:sw:01-mervis:attaching-1-wire-devices-12-set-autogen-dialog.png?direct |}}
===== Debugging solution =====
The Mervis IDE has a feature called **Debugging**, which allows to connect to the running Unipi controller, read its state and even alter the variables on-the-fly. To start the debugging, click on the **Start Debugging** button on the **Ribbon**.
{{ :en:sw:01-mervis:attaching-1-wire-devices-13-debug.png?direct |}}
To view the variables and their state in debug mode, click on the **Variable Browser** tab on the **Main window**. You will be presented with all the variables available in the controller. You can use searching by **Name**. Our temperature sensor has been autonamed "1W-Thermometer" (check the device in the **Left panel** under the **1wire** channel), so enter this name into the **Name** searchbox. The variable containing the actual temperature is called **1W-Thermometer_Temperature** and its current value in PLC is **29.875** °C.
{{ :en:sw:01-mervis:attaching-1-wire-devices-14-variable-browser.png?direct |}}
===== Programming a temperature regulator =====
We have connected the temperature sensor to our controller and verified, that we can read current temperature. Now we can use it in very simple temperature regulator.
We will be monitoring temperature and if the temperature will be under 30 °C, we will turn the ''RO2.1'' ''ON'' and when the temperature will be greater or equal to 30 °C, we will turn the ''RO2.1'' ''OFF''. The ''RO2.1'' will represent a heating element.
We could "hardwire" the temperature "30 °C" into the program, but we wouldn't be able to change it afterwards other than reprogramming the PLC. Most likely, we would like to set the threshold (or desired) temperature by some knob, buttons or even HMI device. So it is better to define it as another variable and set the threshold by changing the variable's value. Later we can wire this variable to some other HW input.
Our program will therefor need two inputs: ''measured_temperature'' and ''threshold_temperature''. In programming, each variable has to have some type - a definition, of what it can store. It can be integer, real number, boolean, character, string of characters or even more complicated type. Temperature by its nature is real number and so will be our variables ''measure_temperature'' and ''threshold_temperature''.
We also need one output: ''heating_on'', which will be boolean, because the heating will be only ''ON'' or ''OFF'' represented by the boolean values ''TRUE'' and ''FALSE''. The naming ''heating_on'' will help us to identify, that it contains a state of the heating. And we can easilly say, that heating_on = true, then the heating is ON.
Let's start creating our program. Programming has to be done when the **Debugging** is stopped, so stop it by clicking on the **Stop Debugging** on the **Ribbon**, if you have it still running. Then double click on the name of the program in the **Left panel** to display it in the **Main window**.
If you remember, in the **Variable browser**, the name of temperature variable was **1W-Thermometer_Temperature**. The name is autogenerated, and the first part is from the name of the sensor. That's not very descriptive, so we will change the name of the sensor to **office**, because it is measuring temperature in our office. Click on the name of the sensor in the **Left panel**. In the **Properties panel**, you can see property **Name**. Change it's value to **office** and either click on the {{:files:dialog-confirm_button_2.png?nolink|}} or submit by **ENTER** key.
{{ :en:sw:01-mervis:attaching-1-wire-devices-16-sensor-name.png?direct |}}
That will rename the variable **1W-Thermometer_Temperature** to **office_Temperature**. You can check it in the **Variable Browser**. Now we can place the temperature onto the program canvas to **Input area**. Right click on the **Input area** and click on **Global Variables** -> **Insert Existing Variable**. The **Insert Existing Variable** dialog will appear and you can search for the **office_Temperature** variable and confirm the adding by clicking on **OK**
{{ :en:sw:01-mervis:attaching-1-wire-devices-17-selecting-variable.png?direct |}}
Now we need to add second input, the **threshold_Temperature**. This variable doesn't exist yet, so we cannot add it from existing variables as we did with **office_Temperature**. Right click on the **Input area** where you want to place the input and click on **Global Variables** -> **Create New Variable**. In the **Create New Variable** dialog, enter the name **threshold_Temperature**, set the type to **real** and set the default value to **30**. And click on **OK**.
{{ :en:sw:01-mervis:attaching-1-wire-devices-18-create-new-variable-dialog.png?direct |}}
The last thing with setting inputs and outputs is to define the output, the ''RO2.1''. Right click on the **Output area** and click on **Global variables** -> **Insert Existing Variable**. In the list of variables look for **RO** and select the ''Neuron_L503_RO_2.01_w''. If you don't have unit with relay outputs, you can use DO instead, the logic is the same.
{{ :en:sw:01-mervis:attaching-1-wire-devices-19-insert-ro201.png?direct |}}
And if everything went well, you should have similar program canvas
{{ :en:sw:01-mervis:attaching-1-wire-devices-20-inputs-outputs.png?direct |}}
Now we can fill the **Logic area** with some "high level" logic. We need to compare the ''office_Temperature'' against ''threshold_Temperature''. We will need to place some **Function block** to achieve this. Switch the **Left panel** into **FUPLA Box Explorer** tab. You can see a list of categories, which have subcategories, which have subcategories,... Since we don't know, how the desired FB is named, we can only guess where it can be. Since we want to compare two analogue values, it could be in the **Basic Analogue Boxes**, so open the tree in **FUPLA Box Explorer**. We want to compare two variables, which has something to do with **Mathematics** category - open it. And you can see **Compare Functions** at the bottom of the category. Open it, and you can see a list of FBs with encryptic names like **eq**, **ge**, **gt**,... Good thing about Mervis IDE is the very extensive help manual. You can right click on each box and select **Help** to learn more about each of the FBs. The correct box we are looking for is **LT**, or **Less than**.
{{ :en:sw:01-mervis:attaching-1-wire-devices-21-compare-functions.png?direct |}}
Grab the **LT** FB and place it onto the **Logic area**.
{{ :en:sw:01-mervis:attaching-1-wire-devices-22-placed-block.png?direct |}}
The help for this block says //Output is TRUE if any previous input is less than any next input//. We can see the block has two inputs - ''in1'' and ''in2'', and one output ''=>''. By the logic, we want the ''heating_on'' on to be ''TRUE'', if the ''office_Temperature'' is less then ''threshold_Temperature''. To comply with the block definition, the ''office_Temperature'' has to be wired to ''in1'' of the block and ''threshold_Temperature'' wired to ''in2''. The output ''=>'' we will wire to ''heating_on''. Wiring is done by grabing the black dot at the input/output name a pulling the wire to the dot of the other input/output. The result should look like this.
{{ :en:sw:01-mervis:attaching-1-wire-devices-22-wired-block.png?direct |}}
If you have the correct connections, you can **Build** the solution and if the **Build** succeeds, **Deploy** the solution to the controller.
If your **Deploy** went well, you can **Start Debugging**. In the debugging mode, you can see actual values of each input and output of each block. You can see temperature in our office is 29.625 °C, which is less then threshold of 30 °C and therefor the heating is ''ON'' (''TRUE'').
{{ :en:sw:01-mervis:attaching-1-wire-devices-23-debugging-low.png?direct |}}
I warmed up the sensor a little bit and now it shows 30.875 °C which is more than 30 °C and therefor the heating is ''OFF'' (''FALSE'')
{{ :en:sw:01-mervis:attaching-1-wire-devices-23-debugging-high.png?direct |}}
Also the relay on your Unipi controller should switch ''ON'' and ''OFF''. If yes, congratulations! You just created your very first temperature regulator.
===== Download =====
You can download the whole project here: {{ :en:sw:01-mervis:attaching-1-wire-devices.zip |}}