Schema

Meta Information

Mortar.io stores device information and sensor values in PubSub event node items. Event node meta information is contained item called 'meta', references in 'reference', storage information is stored in the 'storage' item.

Devices

Device meta information is stored within the 'meta' item. Device meta information holds information about the device and transducers associated with the device.

The definition of the meta informaiton item is given bellow. For examples visit Device Examples

<xs:element name='meta'>
    <xs:complexType>
        <xs:attribute name='name' type='xs:string' use='optional'/>
        <xs:attribute name='manufacturer' type='xs:string' use='optional'/>
        <xs:attribute name='model' type='xs:string' use='optional'/>
        <xs:attribute name='serial' type='xs:string' use='optional'/>
        <xs:attribute name='timestamp' type='xs:datetime' use='optional'/>
        <xs:attribute name='geoloc' type='xs:geoloc' use='optional'/>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='transducer'/>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='template'/>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='property'/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

  • name - Human readable name of the device.
  • manufacturer - Device manufacturer. See manufacturer list for specifications for this, if not present it is possible to extend this type.
  • model - Device model specification as defined by manufacturer.
  • serial - Device serial number, if provided or accessible.
  • transducer - Element that describes a transducer.
  • interface - Element that describes a mapping between transducers and common interfaces for this such as lighting, see Interfaces for more details.
  • property - Property extends the schema for instances when adapters need specific information about a device to communicate with it.
  • geoloc - Follows https://xmpp.org/extensions/xep-0080.html description of location.

Transducer

Transducer meta information provides context about what transducer values mean. It also provides the identifier of the transducer, which specifies the name of the item to listen for value packets to be sent to.

The definition of the transducer information item is given bellow. For examples visit Transducer Examples


<xs:element name='transducer'>
    <xs:complexType>
        <xs:attribute name='name' type='xs:string' use='required'/>
        <xs:attribute name='unit' ref='unit' use='required'/>
        <xs:attribute name='manufacturer' type='xs:string' use='optional'/>
        <xs:attribute name='model' type='xs:string' use='optional'/>
        <xs:attribute name='serialNumber' type='xs:string' use='optional'/>
        <xs:attribute name='canActuate' type='xs:boolean' use='optional'/>
        <xs:sequence>
            <xs:element minOccurs='0' maxOccurs='unbounded' ref='property'/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

  • name - Human readable transducer name. Required to be unique among a device. Required to not match the names of any other meta item.
  • unit - Element describing the data values to expect from transducer.
  • manufacturer - If the transducer can be thought of a different device from the device, the manufacturer of that transducer.
  • transducerModel - The manufacturer id of the transducer model, if available.
  • serialNumber - The manufacture id for the transducer, if available.
  • property - Extensible transducer properties.

Properties

It is often useful to extend a device or transducer. For example it might be useful to specify a ObjectID for a BACnet device or transducer, here the name would be "ObjectID" and the value is the object's id.

For more examples of how this makes the task of writing adapters easier see [[Device Adapters]].

             
<xs:element name='property'>
    <xs:complexType>
        <xs:attribute name='name' type='xs:string' use='required'/>
        <xs:attribute name='value' type='xs:string' use='required'/>
    </xs:complexType>
</xs:element>
  • name - Name of the property.
  • value - Value of the property.

Units

<xs:element name='unit'>
    <xs:complexType>
        <xs:attribute name='units' ref='allowedUnits' use='required' />
        <xs:sequence>
            <xs:strings minOccurs='0' ref='xs:string'>
        </xs:sequence>
        <xs:attribute name='minValue' type='xs:float' use='optional'/>
        <xs:attribute name='maxValue' type='xs:float' use='optional'/>
        <xs:attribute name='resolution' type='xs:float' use='optional'/>
        <xs:attribute name='precision' type='xs:float' use='optional'/>
        <xs:attribute name='accuracy' type='xs:float' use='optional'/>
    </xs:complexType>
</xs:element>

Units provide a common language for sensor values. They also provide a range of values for transducer inputs and outputs. In the case of enums string and values are specified.

Here is the list of suggested units. This list can be extended to support other measurements.


<xs:simpleType name='allowedUnits'>
    <xs:restriction base="xs:string">
        <xs:enumeration value='meter'/>
        <xs:enumeration value='gram'/>
        <xs:enumeration value='second'/>
        <xs:enumeration value='ampere'/>
        <xs:enumeration value='kelvin'/>
        <xs:enumeration value='mole'/>
        <xs:enumeration value='candela'/>
        <xs:enumeration value='radian'/>
        <xs:enumeration value='steradian'/>
        <xs:enumeration value='hertz'/>
        <xs:enumeration value='newton'/>
        <xs:enumeration value='pascal'/>
        <xs:enumeration value='joule'/>
        <xs:enumeration value='watt'/>
        <xs:enumeration value='coulomb'/>
        <xs:enumeration value='volt'/>
        <xs:enumeration value='farad'/>
        <xs:enumeration value='ohm'/>
        <xs:enumeration value='siemens'/>
        <xs:enumeration value='weber'/>
        <xs:enumeration value='tesla'/>
        <xs:enumeration value='henry'/>
        <xs:enumeration value='lumen'/>
        <xs:enumeration value='lux'/>
        <xs:enumeration value='becquerel'/>
        <xs:enumeration value='gray'/>
        <xs:enumeration value='sievert'/>
        <xs:enumeration value='katal'/>
        <xs:enumeration value='liter'/>
        <xs:enumeration value='square meter'/>
        <xs:enumeration value='cubic meter'/>
        <xs:enumeration value='meter per second'/>
        <xs:enumeration value='meter per second squared'/>
        <xs:enumeration value='reciprocal meter'/>
        <xs:enumeration value='kilogram per cubic meter'/>
        <xs:enumeration value='cubic meter per kilogram'/>
        <xs:enumeration value='ampere per square meter'/>
        <xs:enumeration value='ampere per meter'/>
        <xs:enumeration value='mole per cubic meter'/>
        <xs:enumeration value='candela per square meter'/>
        <xs:enumeration value='kilogram per kilogram'/>
        <xs:enumeration value='volt-ampere reactive'/>
        <xs:enumeration value='volt-ampere'/>
        <xs:enumeration value='watt second'/>
        <xs:enumeration value='percent'/>
        <xs:enumeration value='enum'/>
        <xs:enumeration value='lat'/>
        <xs:enumeration value='lon'/>
    </xs:restriction>
</xs:simpleType>  

Templates

The interface element describes the mapping between common interfaces and the device. The interface element stores the transducers associated witha an interface name.

The definition of the transducer information item is given bellow. For more information on what interfaces are available visit [[Templates]] .

             
<xs:element name='template'>
    <xs:complexType>
        <xs:attribute name='name' type='xs:string' use='required'/>
        <seqence>
           <xs:element minOccurs='0' maxOccurs='unbounded' ref='transducer'/>
        </sequence>       
    </xs:complexType>
</xs:element>

Geolocation Streams

The geolocation item stores location information associated with an event node.


<xs:element name=geoloc>
   <xs:complexType> 
      <xs:sequence>
         <xs:element minOccurs='0' maxOccurs='1'ref='geoloc' xmlns='http://jabber.org/protocol/geoloc'/>
      </xs:sequence>
   </xs:complexType>
</xs:element>

Transducer Streams

It is important that the Units described earlier can be used for a number of data types.


<xs:element name='transducerData'>
    <xs:complexType>
            <xs:attribute name='name' type='xs:string' use='optional'/>
            <xs:attribute name='value' type='xs:string' use='required'/>
            <xs:attribute name='timestamp' type='xs:datetime' use='optional'/>
    </xs:complexType>
</xs:element>

Send transducerSetData stanzas to the [uuid]_act node to send actuation commands.


<xs:element name='transducerSetData'>
    <xs:complexType>
            <xs:attribute name='name' type='xs:string' use='optional'/>
            <xs:attribute name='value' type='xs:string' use='required'/>
            <xs:attribute name='timestamp' type='xs:datetime' use='optional'/>
    </xs:complexType>
</xs:element>

Reference Item


<xs:element name = 'reference'>
<xs:complexType>
   <xs:element name='type' type='referenceType' use='required'/>
   <xs:attribute name='node' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>

<xs:simpleType name='referenceType'>
    <xs:restriction base="xs:string">
        <xs:enumeration value='parent'/>
        <xs:enumeration value='child'/>
        <xs:enumeration value='neighbor'/>
  </xs:restriction>
</xs:simpleType>