How To - 1-Wire sensors

This article will explain how to integrate 1-Wire sensors into OpenRemote 2.0 system.
You will need following to finish the integration:

• 1-Wire sensors + controller working on your system
• owserver from OWFS project configured to work with your network
• OpenRemote Online Designer account
• OpenRemote controller that supports 1-Wire protocol

To avoid confusion, whenever OWFS will be typed in all upper case, it refers to OWFS as whole project and suite of programs (such as owfs, owserver, owhttpd).
Every time owfs or owserver will be typed in italic, it refers to specific program.

1-Wire hardware

Current implementation of 1-Wire support in OpenRemote allows only read access to 1-Wire network. In general, if you can read value from 1-Wire device via OWFS, you can access this value via sensor in OpenRemote. In future it is expected that write functionality will be provided. This will, for example, allow users to control external system via relays.

owserver and owfs

Because OpenRemote uses owserver to communicate with physical 1-wire devices, we need to have this part configured and working first. You can find both the software and guide how to configure owfs/owserver on the homepage of the OWFS project.

Most typical usage pattern of OWFS is to use it as a filesystem. This is very nice and useful access method to 1-wire that provide easy way to test all the devices. In the examples you can find on the net, you will often see owfs connecting directly to your 1-wire hardware. This is fine for initial tests of 1-wire configuration, but for later use, it is preferred to use owserver as an intermediate layer. This will allow us to "share" 1-wire network access between many different applications (one of them will be our OpenRemote Controller and other still may be owfs or owhttpd). As you will find on OWFS project page, parameters for owfs and owserver are almost the same, so after you find best settings for your 1-wire network with owfs, you can use the same settings with owserver. This tutorial will not go into details about how to install OWFS on your system, but you can find plenty of information on links you can find at the bottom of this tutorial.

Let's assume you successfully installed OWFS and know how to connect to 1-Wire hardware.
First, we will start owserver:

/opt/owfs/bin/owserver --device=/dev/ttyUSB0 -p 4304

This will start owserver that will access 1-wire controller on serial port /dev/ttyUSB0 and owserver will listen on port 4304 (this is default port, you can change it to whatever you need).

If your 1-wire network contains more sensors, it may be convenient to assign aliases to your devices. To do this, create new file that will contain mapping between device address and alias, for example:

28.25E9E3010000 = OW1_Kitchen
28.B9DFE3010000 = OW1_Attic
26.8A75E7000000 = OW2_Bathroom
26.D076E7000000 = OW2_Exterior
1F.E9E803000000 = Channel1

(Optional) If you want to still have access to 1-Wire via filesystem (owfs), you can start it this way:

/opt/owfs/bin/owfs --allow_other --mountpoint=/var/1-Wire -s localhost:4304

"-s localhost:4304" is important here, since instead of direct access to hardwire, owfs is instructed to access 1-Wire via owserver that we started on port 4304.

(Optional) It may be convinient to start owhttpd that allows you to browse your 1-wire network in web browser:

/opt/owfs/bin/owhttpd -s localhost:4304 -p 18888

In this example, owhttpd will listen on port 18888.

Before you proceed to OpenRemote configuration, check if you can access your 1-wire devices via owfs or owhttpd. This way, you can verify paths to devices and attributes of these devices.

OpenRemote Online Designer

Now, let's create some screen in OpenRemote Online Designer. Online Designer already supports 1-Wire protocol, so all you need is account to log into it.

Our task will be to access temperature and humidity sensor values.

Create new Device

In "Building Modeler", create new device (New>New Device)

Create commands

Still in "Building Modeler", select device that was created in step 1 and click on New>New Command
Specify name and select "1-Wire Protocol" as protocol.

1-Wire specific settings:

• Hostname - ip address or hostname of owserver
• Port - port where owserver is listening
• Device Address - path to target 1-Wire device. For example, if we can access our device via owfs as /var/1-Wire/OW1_Kitchen/ (where owfs mountpoint is set to /var/1-Wire) then path to our device is "/OW1_Kitchen"
• Sensor attribute - name of attribute of 1-Wire device that we want to read. For thermometer, value is most usually "temperature", for humidity sensors it is "humidity".
• Minimum refresh time - to avoid hammering of the 1-Wire network with too many requests, value is cached as long as specified in this field.

Sensor attribute may point to any filename that you can see in owfs. For example, thermometer DS18B20 has (among others) following files in its directory: "temperature","temperature9","temperature10","temperature11",... you can use any of these as source for your command/sensor. You can find meaning of these files in OWFS documentation for DS18B20. Similarly, you can find there documentation for other device types.

Minimum refresh time is ignored in case when there is no correct cached value. If cached value is expired (older than specified time) and read from owserver fails, old value with "!" attached is stored but on next request, controller will retry read from owserver.

Since we are going to configure second command that will read humidity, click on "Submit and continue". This will store our current settings, but preserver filled-in values. We can then easily update settings without the need to re-enter all the values again.

In this command, we access device "OW2_Exterior" and it's attribute "humidity".
Since we are not going to add any other command, click on "Submit".

Create sensors

Now we will create sensor, that will use previously created commands to access values of our 1-Wire devices.
Click on "New>New Sensor"

We will call our first sensor "KitchenTemperature". Select command "GetKitchenTemperature" and choose Type "range" and specify min and max temperature for this sensor.

At this moment, type is ignored and min/max values are not taken into account.

When all values are entered, click on "Submit" to save sensor.

Again, click on "New>New Sensor" to create sensor for exterior humidity.

Name of second sensor will be "KitchenTemperature". Command to get value from 1-Wire network is set to be "GetExteriorHumidity".

Type of sensor is range. Since this is relative humidity, it can be any value between 0 and 100 (%).
Submit this dialog to save the sensor.

Use sensor in UI Designer

Now we have configured everything necessary to use sensor value in UI Designer. To display sensor value, you can create Label and select sensor "KitchenTemperature" or "ExteriorHumidity".

Useful links

Following links may be useful for 1-Wire beginners:

OWFS Project homepage
1-Wire and Ubuntu

(If you have any article that helped YOU to get 1-Wire up and running, please share it with others!)