You are here: OWFS 1-Wire File System » Advanced » External sensor support

External sensors

This page describes a new element -- external device support.

The motivation is a number of requests on the developers mailing list, most recently


The initial design goals:
  • Devices will be supported by a plug-in skeleton where individual read and write routines will be external programs.
    • Programs can be in any language
    • The program will receive information from the calling program (device name, property name)
    • Data type and length will be checked by the calling program
  • All external devices will be in the same directory (like 1-wire) but can be pieced out by the "bus.x" structure
  • The supporting structure will be a separate program using the owserver protocol to communicate
    • The program will be called "owexternal"
    • It will seamlessly look like an owserver to calling programs
    • It will be able to send queries upstream
    • It will have anti-loop token support
    • It will handle caching and some administrative properties
  • Configuration will be by text file
    • Two entry types for config
    • First type describes a script for a family of sensors
    • Second layer lists one actual sensor.
  • Sensor list configuration
    • Each sensor (slave) is listed
    • sensor needs a unique name (like the 64-bit 1-wire address)
    • sensor can optionally include a text description
    • sensor needs to give the name of it's family
    • more than one sensor can be of the same family
    • Example syntax:
      SENSOR: bedroom, rtd_family, "Bedroom temperature", "/dev/ttyUSB0"
      • SENSOR: is the first required element indicating that this is part of the sensor list
      • Unique name
      • Family
        • Note that family is the second field in both types of records
      • optional description
    • The three fields are comma separated, and spaces should be quoted or backslash escaped
  • Property configuration
    • Gives a list of the properties supported by the sensor
    • Supports a subdirectory structure for the names
    • Example syntax
      SCRIPT: temperature, rtd_family, t, 1, v, rtd_read.pl, , ,
      • SCRIPT: keyword defines a property and access method (script) for a given sensor property
      • property (name or subdir/name)
      • family that this property pertains to
        • Note that family is the second field in both kinds of records
      • type/length of value:
        • Directory
          • length is gnored
        • integer
          • length is default 12 characters (e.g. i12)
          • specify length as number after i
        • unsigned integer
          • length is default 12 characters (e.g. u12)
        • floating point
          • length is default 12 characters ( e.g. f12)
        • ascii
          • length should be specified
          • e.g. a25 for 25 characters
          • default is 1 character (a1)
        • binary
          • length should be specified in bytes
          • e.g. b32 for 32 bytes
          • default is 1 byte (b1)
        • yes-no value
          • length is default 1 character (e.g. y1)
          • values are only "0" and "1"
        • date
          • length is default 24 characters (e.g. d24)
          • typically formated as "25 mar 2022"
        • temperature
          • length is default 12 characters (e.g. t12)
          • this is a floating point number in the specified temperature scale
          • default "C" Celsius
        • gap (temperature difference)
          • length is default 12 characters (e.g. g12)
          • default "C" Celsius
        • pressure
          • length is default 12 characters (e.g. p12)
      • array type:
        • 1
          • scalar value
          • a single value of the type given above
        • 8
          • an array of 8 elements
          • e.g. val.0, val.1, ... val.7
          • 0 based
          • all calls will be for a single element
        • +8
          • an array of 8 elements
          • calls will be for all the elements together
          • usually separated by commas
          • except binary values have no separation
        • -1
            • a sparse array
            • index is any number
        • F
            • array indexed with letters
            • val.A, val.B, ... val.F
            • includes last letter
            • all calls will be for a single element
            • case ignored
        • +F
          • array indexed with letters
          • calls return all the elements at once
          • case ignored
        • -A
            • sparse array
            • alphanumeric index
            • case ignored
      • persistance (for caching)
        • fixed
        • stable
        • volatile
        • time
        • uncached
      • Read function (optional)
      • Write function (optional)
      • property-specific data string (optional)
    • The structure string takes precedence over the other entries.
      for instance, if the property is structured as "ro" (read-only) then
      a write function won't be called, even if supplied
    • There are some automatic properties for every external sensor:
      • family (the family name given in the SENSOR entry)
      • description (the description given in the SENSOR entry)
      • address (the unique name given in the SENSOR entry)
      • type "external"
  • Read function
    • Called with the following arguments:
      • family name
      • property name
      • extension (or null string)
      • description (or null string)
      • "read" keyword
      • length (in bytes)
      • offset (0 based)
      • property-specific data string (or null string)
      • structure string
    • Many of the calling arguments are redundant to the read function, but allow more generic routines to be used
    • Return value:
      • 0 success
      • 1 failure (error)
    • Return data
      written to stdout
  • Write function
    • called with the following arguments:
      • family name
      • property name (or null string)
      • extension (or null string)
      • "write" keyword
      • length expected (in bytes)
      • offset (0 based)
      • property-specific data (or null string)
      • structure string
    • return value:
      • 0 success
      • 1 failure (error)
    • Written data
      sent via stdin

^ Top

Previous page: Structure Directory
Next page: Help