BiTXml. M2M Communications Protocol. Rel

Size: px

Start display at page:

Download "BiTXml. M2M Communications Protocol. Rel"

Bruno Ward
5 years ago
Views:

1 BiTXml M2M Communications Protocol Rel Last revision:

2 Index FOREWORDS... 4 FOREWORDS TO THE SECOND EDITION... 4 CHANGES... 5 INTRODUCTION REFERENCE MODEL BITXML V2 PROTOCOL DEFINITION: SYNTAX ERROR VALUE Description Syntax Semantic Examples SYSTEM STATE VALUE Description Syntax Semantic Examples HISTORY VALUE Description Syntax Semantic Examples INITIALIZATION VALUE Description Syntax Semantic Examples GATEWAY REINITIALIZATION COMMAND Description Syntax Return values Semantic Examples STATE RETRIEVAL COMMAND Description Syntax Return value Semantic Examples HISTORY RETRIEVAL COMMAND Description Syntax Return value Semantic Examples STATE SETUP COMMAND Description Syntax Return value Semantic Examples EVENT VALUE Description Syntax BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 2 of 101

3 2.9.3 Return values Semantic Examples BITXML V2 PROTOCOL DEFINITION: DATA FLOWS COMPLETE GATEWAY APPLICATION INITIALIZATION INITIALIZATION ERROR DATA FLOW CONDITION MONITOR DATA FLOW HISTORY MONITOR DATA FLOW COMMANDS SERVER DATA FLOW RECONFIGURATION CHECKER DATA FLOW APPENDIX A BITXML V2 SCRIPTING LANGUAGE GENERAL DESCRIPTION SYNTAX <IF> CONDITIONAL STATEMENT <WHILE> ITERATION STATEMENT <DELAY> OPERATOR <EXIT> OPERATOR <SET> OPERATOR <GET> OPERATOR <RET> OPERATOR <PORT> OPERATOR EXAMPLES APPENDIX B BITXML DNS PROTOCOL DESCRIPTION START-UP MESSAGE KEEP-ALIVE MESSAGE APPENDIX C BITXML MESSAGE TUNNELLING DESCRIPTION DATA MESSAGE APPENDIX D - SAMPLE GATEWAY APPLICATION START-UP META CODE BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 3 of 101

4 Forewords While other efforts have been carried out to identify a 'killer protocol' in the M2M arena, it seems that presently no one has already reached the goal. So, one way to approach the problem might be the definition of an extendible protocol, targeting at first the core functionalities commonly required by M2M applications, lying on a very general architectural model: this is in fact the BiTXml protocol design approach. Our main guidelines have been readability and easy extendibility of the protocol specs, including the support for different I/O ports, network protocols, and core functionalities. The result, as an evolutionary project, wants to be of help to everyone is facing M2M projects and needs a reference framework to express commands and control processes in an easy yet (hopefully enough!) powerful way. The authors, Milan (Italy), Jun Forewords to the second edition Based on our most recent experiences across different M2M projects, a whole new set of hints and requirements have been considered and studied to completely revisit the first release of the BITXml protocol: the result is a more accurate and shaped language, expressing a new set of concepts, in a more accurate form of expression versus the previous edition, at the price of a few backward incompatibilities. The evolution of the protocol is still underway, but we feel we have placed important additional milestone references with this new version of BITXml. The authors, Milan (Italy), Dec BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 4 of 101

5 Changes Rel Introduced a property type attribute (optional, in init value), allowing strong type definition for properties values. A set of predefined types is defined in order to easily identify basic value types, as long as the possibility to define custom enumerative values. Introduced optional attibute clean in history-def element definition, defaulting to false, which enables the cleaning of the history content upon successful forwarding. Introduced optional attibute clean in gethistory command definition, defaulting to false, which enables the cleaning of the history content upon successful forwarding. Introduced mixed content in system events Introduced the version element optionally used by the BOOT event type to specify the gateway manager version Introduced new system event type ALIVE used to notify gateway operativity; Introduced new system event type PWRDWN used to notify when the gateway manager recognizes a power break; Introduced new system event type PWRUP used to notify when the gateway manager recognizes a power break has resumed; Introduced new system event type ERRMEM used to notify when the gateway manager recognizes a shortage or an error in memory resources; Introduced new system event type ERRSTRG used to notify when the gateway manager recognizes a shortage or an error in mass storage; Introduced new system event type LOC used to notify geographical localization of the gateway manager; the detail of the event has the state:location format. Introduced new command getpos, used to retrieve the current geographical position (as a state value containing a location element) Introduced new meta-process PositionMonitor which allows the monitoring of the current geographical position (for gateways supporting GPS devices as embedded units) and the delivery of events based upon timed schedulation. Delivered events are system event of type LOC. The PositionMonitor meta process handling MUST be ignored when the gateway has no GPS built-in capability. This feature may obsolete the positioning port type ps-o wherever a real gateway box supports embedded GPS devices. BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 5 of 101

6 Introduced the subscribed gateway manager type, which enables the reception (using the Server Monitor) and the automatic handling of events sent by foreign parties. (IMPLEMENTARE IN SDK JAVA E C#) Introduced the tunnelling feature, which enables the delivery of application specific, non-bitxml messages, to the server monitor. (IMPLEMENTARE IN SDK JAVA E C#) Breaking changes the state ps-o value uses a location element to describe geographical position (attributes were used). Rel Initialization properties definition (in init value) are now (optionally) available for connected and detached gateway managers too. Awakeners configurations now may use their definition element content to configure properly A new gateway manager (optional) subspecifier has been added in order to expand with custom extra information (with no protocol definition for it) the data exchanged between the gateway manager and the master unit Rel Introduced awakenable connected gateway managers ReInit command can force the server monitor to disconnect Introducted new error codes related to the awake configuration BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 6 of 101

7 Introduction The BiTXml communication protocol has been designed to implement an application level of the (OSI-based) communication stack reference, with the main goal to standardize the way commands and control information are exchanged for the specific target of M2M communication demands (i.e. communication with generic devices with or without processing power on board like sensors, actuators, as well as air conditioning systems, lifts,.. or a combination of them). The current protocol specification defines: 1. The abstraction of a BiTXml gateway application 2. The abstraction of a BiTXml controller 3. The syntax and the semantic of a set of values used to exchange data between two communicating parties 4. The syntax and semantic of a set of commands used to drive the devices connected to the BiTXml gateway application 5. The syntax and semantic for events, generated by the BiTXml gateway application following the recognition of specific conditions on the controlled devices The protocol syntax will be meta-coded in Xml Schema language. The protocol semantic will be defined in natural language (no formalization will be provided). BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 7 of 101

8 1. Reference model The architectural reference model underlying the BiTXml protocol is shown in Fig. 1. Devices 1..1 I/O Ports 1..N BiTXml Commands/Replies BiTXml Application Gateway Network Transport BiTXml Controller BiTXml Events Fig. 1 Architectural reference model The main parts of the reference model are: 1. BiTXml gateway application: any kind of software application, speaking the BiTXml language, working as an 'intelligent' remote execution unit 2. BiTXml controller: any kind of software application speaking the BiTXml language, working as the master (controlling) unit for one or more application gateways 3. Network transport: any kind of network transport layer 4. I/O ports: any kind of connection port enabling the control of whatever physical or logical device connected. Actually supported connection ports range through analog and digital GPIOs, positioning devices, serial ports and user-definable (logical) ports. 5. Devices: any kind of logical or physical device connectable to the available I/O ports. While no detail may be given for the BiTXml controller component, being it the side where applications or middleware solutions as well may take the role of master unit, an architectural model for a standard gateway application may be shown (see Fig. 2): BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 8 of 101

9 BiTXml Gateway Application Device/Port Drivers Async processes Reconfig. checker Startup req. BiTXml DNS client DNS protocol History Monitor BiTXml history events Conditions Monitor BiTXml events History retrieval replies Condition replies History retrieval commands Condition commands BiTXml Server BiTXml replies Port-level commands Sync processor BiTXml Protocol Commands Interpreter BiTXml commands Network Transport Layer Fig. 2 - Standard gateway application reference model The application gateway is surrounded by the network layer (right side of the drawing) and the device/ports drivers at the other side. The gateway may be split into two main logical parts: asynchronous processing synchronous processing Asynchronous processing involves several executing units, each one accomplishing a welldefined function within the system. Currently defined asynchronous units are: Conditions monitor: a set of conditions may be installed on the system and polled for matches; if any match is found, an event for each match is generated and sent to the master unit. BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 9 of 101

10 History monitor: a list of port state requests may be installed on the system, executed by the monitor, so that any state reply is stored locally in a non-volatile fixed-size FIFO area. The history is sent to the master unit in a programmable fashion. Reconfiguration monitor: a schedule table may be installed on the system, allowing the monitor to periodically check for reconfiguration needs. Synchronous processing allows the basic execution of BiTXml commands, returning the replies for each executed command. Currently defined synchronous units are: BiTXml Server: network client, connected with the controlling unit, able to receive BiTXml commands, execute them using the commands interpreter, and return the corresponding results. BiTXml DNS: a custom protocol client, specifically designed to allow the handling of gateways having their network address dynamically assigned (such as GPRS- or WI-FI- networked devices), used when the gateway is connected (see later). The DNS is responsible to connect to the Controller in order to register the gateway, and to maintain the connection open where network transport may be broken by operator-asserted timeouts. Gateway applications can be configured in three fundamental ways: connected detached custom Connected gateway applications must run the protocol server and the DNS client, and may run conditions and history monitors. Detached gateway applications must not run the protocol server and the DNS client, and must run at least one from the condition and history monitors. Custom applications should use the configuration at their wish, although respecting the message flow defined by the protocol. The reconfiguration monitor may be run by whatever type of gateway or application. BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 10 of 101

11 2. BITXML V2 Protocol Definition: Syntax BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 11 of 101

12 2.1 Error Value Description The <error> value is used to code any error that happens in the system, both following the execution of a command, and following an exceptional (self-recognized) condition; it may be returned as an event to the controlling unit (see the Event value description) when an asynchronous monitors must communicate an error Syntax <?xml version="1.0" encoding="utf-8"?> <xs:schema id="error" xmlns:xs=" targetnamespace=" xmlns:self=" > <xs:element name="error" type="self:errornodetype" /> <xs:complextype name="errornodetype"> <xs:simplecontent> <xs:extension base="xs:string"> <xs:attribute name="id-device" type="xs:string" use="required" /> <xs:attribute name="datetime-utc" type="xs:datetime" use="required" /> <xs:attribute name="code" type="self:codetype" use="required" /> <xs:attribute name="extra-info" type="xs:string" use="optional" /> </xs:extension> </xs:simplecontent> <xs:simpletype name="codetype"> <xs:restriction base="xs:nonnegativeinteger">  <xs:enumeration value="0" />  <xs:enumeration value="1" />  <xs:enumeration value="2" />  <xs:enumeration value="3" />  <xs:enumeration value="100" />  <xs:enumeration value="110" />  <xs:enumeration value="120" />  <xs:enumeration value="130" />  <xs:enumeration value="140" />  <xs:enumeration value="500" /> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 12 of 101

13  <xs:enumeration value="501" />  <xs:enumeration value="502" />  <xs:enumeration value="503" />  <xs:enumeration value="504" />  <xs:enumeration value="505" />  <xs:enumeration value="510" />  <xs:enumeration value="511" />  <xs:enumeration value="512" />  <xs:enumeration value="513" />  <xs:enumeration value="1000" />  <xs:enumeration value="1001" />  <xs:enumeration value="1002" />  <xs:enumeration value="1003" />  <xs:enumeration value="1004" />  <xs:enumeration value="1005" />  <xs:enumeration value="1006" />  <xs:enumeration value="1007" />  <xs:enumeration value="1008" />  <xs:enumeration value="1009" />  <xs:enumeration value="1010" />  <xs:enumeration value="1011" />  <xs:enumeration value="1012" />  <xs:enumeration value="1013" />  <xs:enumeration value="2000" />  <xs:enumeration value="2001" />  <xs:enumeration value="2002" />  <xs:enumeration value="2003" />  <xs:enumeration value="2004" />  <xs:enumeration value="2005" />  BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 13 of 101

14 <xs:enumeration value="2006" />  <xs:enumeration value="2010" />  <xs:enumeration value="2011" />  <xs:enumeration value="3000" />  <xs:enumeration value="5000" />  <xs:enumeration value="6000" /> </xs:restriction> </xs:simpletype> </xs:schema> The attribute contains the (originating) gateway application logical name. The attribute contains the UTC date and time when the error has occurred. The attribute contains the numeric error code. The attribute may contain any additional user information. The inner text of the <error> element may contain error details Semantic The attribute must assume one of the following values: Value Detail message Description 0 - No error - unused 1 Custom message describing the Generic system error error 2 Custom message describing the Syntax error error 3 - Unavailable memory 100 Gateway identifier Invalid id-device value - device not registered. Error issued by the controller to the gateway application when the logical name sent to the controller (with a BOOT system event) is not registered Gateway is registered but not operable. Error issued by the controller to the gateway application when the logical name sent to the controller (with a BOOT system event) is registered but the gateway has been taken out of operation (disabled) No configuration available. Error issued by the controller to the BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 14 of 101

15 gateway application when no new configuration is available (requested with a REINIT system event) Configuration available. Error issued by the controller to the gateway application when a new configuration is available (requested with a REINIT system event) No Bridge available for connected support 500 Port identifier; custom message describing the error 501 Custom message describing the error 502 Custom message describing the error 503 Custom message describing the error 504 Custom message describing the error 505 Custom message describing the error 510 Custom message describing the error 511 Custom message describing the error 512 Custom message describing the error 513 Custom message describing the error Port initialization error. Error starting condition monitor. Error issued by the gateway application when the condition monitor fails to start correctly Error starting history monitor. Error issued by the gateway application when the history monitor fails to start correctly Error starting reconfiguration checker. Error issued by the gateway application when the reconfiguration checker fails to start correctly Error starting on board BiTXml server Error issued by the gateway application when the command server fails to start correctly Error starting BiTXml DNS client. Error issued by the gateway application when the BiTXml DNS client fails to start correctly Error executing synchronous <getstate> command Error executing synchronous <setstate> command Error executing synchronous <gethistory> command Error executing synchronous <reinit> command 1000 Port identifier Invalid I/O port identifier 1001 System port identifier Invalid system port identifier 1002 Port name Invalid I/O port type 1003 Port name; invalid value Invalid I/O port value 1004 Duplicated port identifier Duplicated I/O port identifier 1005 Port name Invalid I/O port direction 1006 Port name Invalid I/O port script 1007 Property identifier Duplicated property identifier 1008 Time value Invalid time value Invalid command. Error issued by the commands server when a malformed command has been submitted for execution BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 15 of 101

16 1010 Invalid value Invalid binary value. Binary values must be hex binary encoded Invalid value Invalid value 1012 Invalid value Invalid date and time value 1013 Property identifier Invalid property identifier 2000 Condition identifier Duplicated condition identifier 2001 Condition name; port identifier ; Wrong minimum value for a range element wrong value 2002 Condition name; port identifier ; Wrong maximum value for a range element wrong value 2003 Wrong value Invalid compare value 2004 Condition name Condition evaluation error 2005 Port name Script execution error 2006 Port name Operation execution error No awaker defined 2011 Awaker method name Invalid awaker Undefined gateway position 5000 Custom message describing the error Unexpected error Examples <?xml version="1.0" encoding="utf-8"?> <error xmlns=" id-device=" " code="1000" >DIG-28</error> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 16 of 101

17 2.2 System State Value Description The <state> value codes a partial or complete gateway state, which is composed from the state of some or all of the configured ports. Optionally, a location element can be present, stating the current geographical position of the gateway. The state of a port depends on its type: for analog readable (either INPUT or INPUTOUTPUT type) ports, the state is the actual digitized value of the port, normalized within the given port range configured by the initialization for digital readable (either INPUT or INPUTOUTPUT type) ports, the state is the actual pin value (either true (1) or false (0)) for positioning ports, the state is the actual geographical position detected by the positioning device for serial and user readable (either INPUT or INPUTOUTPUT type) ports,the state may be either the last binary or textual value read from the port, or the current port value. If the port is not an input-only port, the state must be reset to an empty value after each retrieval Syntax <xs:schema id="state" xmlns:xs=" elementformdefault="qualified" attributeformdefault="unqualified" targetnamespace=" xmlns:self=" > <xs:element name="state" type="self:statenodetype"/> <xs:complextype name="statenodetype"> <xs:sequence> <xs:element ref="self:location" minoccurs="0" maxoccurs="1"/> <xs:sequence maxoccurs="unbounded"> <xs:choice> <xs:element ref="self:a-io" /> <xs:element ref="self:d-io" /> <xs:element ref="self:s-io" /> <xs:element ref="self:ps-o" /> <xs:element ref="self:user-io" /> </xs:choice> <xs:attribute name="id-device" type="xs:string" use="required" /> <xs:attribute name="datetime-utc" type="xs:datetime" use="required" /> <xs:attribute name="extra-info" type="xs:string" use="optional" default=""/> <xs:element name="location" type="self:loctype" /> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 17 of 101

18 <xs:complextype name="loctype" mixed="true"> <xs:sequence minoccurs="0">  <xs:element name="acq" type="xs:datetime" minoccurs="0" />  <xs:element name="lon" type="xs:float" minoccurs="1" />  <xs:element name="lat" type="xs:float" minoccurs="1" />  <xs:element name="alt" type="xs:float" minoccurs="0" />  <xs:element name="vel" type="xs:float" minoccurs="0" />  <xs:element name="sat" type="xs:positiveinteger" minoccurs="0" /> <xs:element name="ps-o" type="self:geopostype"/> <xs:complextype name="geopostype"> <xs:sequence> <xs:element ref="self:location" minoccurs="0" maxoccurs="1"/> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="error" type="xs:string" use="optional"/>  <xs:element name="a-io" type="self:aiotype" /> <xs:complextype name="aiotype"> <xs:simplecontent> <xs:extension base="self:aiovaluetype"> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="error" type="xs:string" use="optional"/> </xs:extension> </xs:simplecontent> <xs:simpletype name="aiovaluetype"> <xs:union membertypes="xs:double"> <xs:simpletype> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 18 of 101

19 <xs:restriction base="xs:string"> <xs:enumeration value="error" /> <xs:enumeration value="" /> </xs:restriction> </xs:simpletype> </xs:union> </xs:simpletype> <xs:element name="d-io" type="self:diotype" /> <xs:complextype name="diotype"> <xs:simplecontent> <xs:extension base="self:diovaluetype"> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="error" type="xs:string" use="optional"/> </xs:extension> </xs:simplecontent> <xs:simpletype name="diovaluetype"> <xs:union membertypes="xs:boolean"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:enumeration value="error" /> <xs:enumeration value="" /> </xs:restriction> </xs:simpletype> </xs:union> </xs:simpletype> <xs:element name="s-io" type="self:siotype" /> <xs:complextype name="siotype"> <xs:choice minoccurs="1" maxoccurs="1"> <xs:element name="error" type="xs:string" /> <xs:element name="binary" type="xs:hexbinary" /> <xs:element name="text" type="xs:string" /> </xs:choice> <xs:attribute name="id" type="xs:string" use="required" /> <xs:element name="user-io" type="self:useriotype" /> <xs:complextype name="useriotype"> <xs:choice minoccurs="1" maxoccurs="1"> <xs:element name="error" type="xs:string" /> <xs:element name="binary" type="xs:hexbinary" /> <xs:element name="text" type="xs:string" /> <xs:element name="xml"> <xs:complextype> <xs:sequence> <xs:any processcontents="skip" minoccurs="1" maxoccurs="1" /> </xs:element> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 19 of 101

20 </xs:choice> <xs:attribute name="id" type="xs:string" use="required" /> </xs:schema> The attribute contains the originating gateway logical name. The attribute contains the UTC date and time when the state has been retrieved. The attribute may contain any additional user information. state/a-io elements contain each one the value of an analog I/O port The attribute contains the unique identifier of the analog port The attribute, if defined, contains the error message generated by the value retrieval process. The inner text of the state/a-io element contains the read value for the analog port (or ERROR if the value is not available) state/d-io elements contain each one the value of a digital I/O port The state/d-io@id attribute contains the unique identifier of the digital port The state/a-io@error attribute, if defined, contains the error message generated by the value retrieval process. The inner text of the state/d-io element contains the read value for the digital port (or ERROR if the value is not available) The state/ps-o element contains the geographical position of the gateway, retrieved by a positioning on-board device (such as GPS). The state/ps-o/location@lon attribute contains the actual longitude of the gateway, expressed in degrees with format +/-ddd.ssssss, where ddd are degrees, and ssss are degrees fraction. This attribute may also contain ERROR when no position can be retrieved. The state/ps-o/location@lat attribute contains the actual latitude of the gateway, expressed in absolute degrees with format +/-dd.ssssss, where dd are degrees, and ssss are degrees fraction. This attribute may also contain ERROR when no position can be retrieved. The state/ps-o/location@alt attribute contains the actual altitude of the gateway (expressed in meters above the sea level). The state/ps-o/location@ utc attribute contains the UTC date and time of the position acquisition (fix). The state/ps-o/location@vel attribute contains the gateway speed (expressed in meters pe second) The state/ps-o/location@sat attribute contains the number of satellites involved in the measurement of the gateway position. The state/ps-o@error attribute, if defined, contains the error message generated by the value retrieval process. When defined, the location element must be omitted. state/s-io elements contain each one the value of a serial I/O port (that is, the last set of bytes read from the port) The state/s-io@id attribute contains the unique identifier for the serial port The state/s-io/error element, if defined, contains the error message generated by the value retrieval process. The state/s-io/binary element, if defined, contains the hex binary encoded value retrieved from the port. The state/s-io/text element, if defined, contains the string value retrieved from the port. BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 20 of 101

21 state/user-io elements contain each one the value of a user I/O port (that is, the last set of bytes read from the port) The state/user-io@id attribute contains the unique identifier for the user port The state/user-io/error element, if defined, contains the error message generated by the value retrieval process. The state/user-io/binary element, if defined, contains the hex binary encoded value retrieved from the port. The state/user-io/text element, if defined, contains the string value retrieved from the port. The state/user-io/xml element, if defined, contains the xml value (as a single root element) retrieved from the port Semantic 1. Every port value description element (<ps-o>, <a-io>, <d-io>, <s-io> and <userio>) must have a unique logical identifier, different from every other name used to identify any other port value (of any type) Examples <?xml version="1.0" encoding="utf-8"?> <state xmlns=" id-device=" " datetime-utc=" t13:42:04z" > <ps-o acquisition-time-utc=" t13:43:22z" longitude=" " longitude-side="e" latitude=" " latitude-side="s" altitude="123.33" speed="3.4" visible-satellites="5" /> <a-io id="dss-46">23.4</bitxml:a-io> <d-io id="scx-45">error</bitxml:d-io> <d-io id="ere-89">true</bitxml:d-io> <s-io id="com1"><binary>41540d</binary></bitxml:s-io> </state> <?xml version="1.0" encoding="utf-8"?> <state xmlns=" id-device=" " datetime-utc=" t08:33:44z" > <d-io id="my-switch">true</bitxml:d-io> </state> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 21 of 101

22 2.3 History Value Description The <history> value is the container element for a sequence of <state> values, collected by the history monitor, and returned by <gethistory> commands or encapsulated inside an <event> value by the history monitor f(or asynchronous forwarding to the master unit) Syntax <?xml version="1.0" encoding="utf-8"?> <xs:schema id="history" xmlns:xs=" targetnamespace=" xmlns:self=" xmlns:state=" > <xs:import namespace=" schemalocation="state.xsd" /> <xs:element name="history" type="self:historyvaluetype" /> <xs:complextype name="historyvaluetype"> <xs:sequence> <xs:element ref="state:state" minoccurs="0" maxoccurs="unbounded" /> <xs:attribute name="id-device" type="xs:string" use="required" /> <xs:attribute name="datetime-utc" type="xs:datetime" use="required" /> <xs:attribute name="extra-info" type="xs:string" use="optional" /> </xs:schema> The history@id-device attribute contains the gateway logical name. The history@datetime-utc attribute contains the UTC date and time when the history list has been generated. The history@extra-info attribute may contain any additional user information. The history/state elements contain the retrieved state values Semantic None Examples History element returned as a reply for a <gethistory> command: <?xml version="1.0" encoding="utf-8"?> <history xmlns=" id-device=" " datetime-utc=" t00:01:02z" BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 22 of 101

23 > <state xmlns=" id-device=" " datetime-utc=" t14:20:00z" > <a-io id="dss-46" >22</a-io> <a-io id="sad-89" >3.3</a-io> <d-io id="scx-45" >ERROR</d-io> <d-io id="ere-89" >true</d-io> <s-io id="com1"><binary>41540d</binary></s-io> </state> <state xmlns=" id-device=" " datetime-utc=" t14:25:00z" > <a-io id="dss-46" >22.5</a-io> <a-io id="sad-89" >ERROR</a-io> <d-io id="scx-45" >ERROR</d-io> <d-io id="ere-89" >true</d-io> <s-io id="com1"><binary>41540d</binary></s-io> </state> <state xmlns=" id-device=" " datetime-utc=" t14:30:00z" > <a-io id="dss-46" >22</a-io> <a-io id="sad-89" >NONE</a-io> <d-io id="scx-45" >true</d-io> <d-io id="ere-89" >false</d-io> <s-io id="com1"><binary>41520d</binary></s-io> </state> </history> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 23 of 101

24 2.4 Initialization Value Description The <init> element contains a complete gateway application initialization. The initialization of a gateway application is composed by the following logical parts: ports set-up: definition of all the controlled ports (the ports that may be used by asynchronous and synchronous units). Not all the ports physically or logically available have to be necessarily configured. asynchronous monitors set-up: definition of the asynchronous monitors that must be enabled, with their specific configurations (conditions for the conditions monitor, setstate/getstate requests for history monitor,...) synchronous units (currently the BiTXml commands server unit) Syntax <?xml version="1.0" encoding="utf-8"?> <xs:schema id="init" xmlns:xs=" elementformdefault="qualified" attributeformdefault="unqualified" targetnamespace=" xmlns:self=" xmlns:getstate=" xmlns:setstate=" > <xs:import namespace=" schemalocation="getstate.xsd"/> <xs:import namespace=" schemalocation="setstate.xsd"/>  <xs:element name="init" type="self:initnodetype"/> <xs:complextype name="initnodetype"> <xs:sequence> <xs:element ref="self:io-list" minoccurs="1" maxoccurs="1" /> <xs:choice minoccurs="1"> <xs:element name="connected"> <xs:complextype> <xs:sequence> <xs:element ref="self:server" minoccurs="1" maxoccurs="1"/> <xs:element name="events" type="self:connectedeventstype" minoccurs="0" maxoccurs="1" /> </xs:element> <xs:element name="detached"> <xs:complextype> <xs:sequence> <xs:element name="events" type="self:detachedeventstype" /> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 24 of 101

25 </xs:element> <xs:element name="custom"> <xs:complextype> <xs:sequence> <xs:element ref="self:server" minoccurs="0" maxoccurs="1"/> <xs:element name="events" type="self:connectedeventstype" minoccurs="0" maxoccurs="1" /> <xs:element ref="self:properties" minoccurs="0" maxoccurs="1" /> </xs:element> </xs:choice> <xs:element ref="self:reconfiguration-check" minoccurs="0" maxoccurs="1" /> <xs:attribute name="id-device" type="xs:string" use="required" /> <xs:attribute name="datetime-utc" type="xs:datetime" use="required" /> <xs:attribute name="boot-policy" type="self:bootpolicytype" use="optional" default="request" /> <xs:attribute name="extra-info" type="xs:string" use="optional" />  <xs:simpletype name="bootpolicytype"> <xs:restriction base="xs:string"> <xs:enumeration value="request" /> <xs:enumeration value="standalone" /> </xs:restriction> </xs:simpletype>  <xs:element name="io-list" type="self:iolisttype" /> <xs:complextype name="iolisttype"> <xs:sequence minoccurs="1" maxoccurs="unbounded"> <xs:choice minoccurs="1"> <xs:element ref="self:a-io" /> <xs:element ref="self:d-io" /> <xs:element ref="self:s-io" /> <xs:element ref="self:ps-o" /> <xs:element ref="self:user-io" /> </xs:choice>  <xs:element name="a-io" type="self:aiotype" /> <xs:complextype name="aiotype"> <xs:choice minoccurs="0" > <xs:element name="val" type="xs:double" /> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 25 of 101

26 <xs:element ref="setstate:a-script" /> </xs:choice> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="sys-id" type="xs:string" use="required" /> <xs:attribute name="type" type="self:dirtype" use="optional" default="io" /> <xs:attribute name="analog-min" type="xs:double" use="required" /> <xs:attribute name="analog-max" type="xs:double" use="required" />  <xs:element name="d-io" type="self:diotype" /> <xs:complextype name="diotype"> <xs:choice minoccurs="0" > <xs:element name="val" type="xs:boolean" /> <xs:element ref="setstate:d-script" /> </xs:choice> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="sys-id" type="xs:string" use="required" /> <xs:attribute name="type" type="self:dirtype" use="optional" default="io"/>  <xs:element name="ps-o" type="self:psonodetype" /> <xs:complextype name="psonodetype"> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="sys-id" type="xs:string" use="required" />  <xs:element name="s-io" type="self:siotype" /> <xs:complextype name="siotype"> <xs:choice minoccurs="0" > <xs:element name="val" type="self:condserialiocmdtype" /> <xs:element ref="setstate:s-script" /> </xs:choice> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="sys-id" type="xs:string" use="required" /> <xs:attribute name="type" type="self:dirtype" use="optional" default="io" /> <xs:attribute name="writechar-delay" type="xs:nonnegativeinteger" use="optional" default="0" /> <xs:attribute name="readchar-timeout" type="xs:nonnegativeinteger" use="optional" default="500" /> <xs:attribute name="execution-delay" type="xs:nonnegativeinteger" use="optional" default="0" /> <xs:attribute name="bps" type="self:baudratetype" BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 26 of 101

27 use="optional" default="9600" /> <xs:attribute name="parity-bit" type="self:paritybittype" use="optional" default="none" /> <xs:attribute name="stop-bit" type="self:stopbittype" use="optional" default="1" /> <xs:attribute name="bits-char" type="self:bits4chartype" use="optional" default="8" /> <xs:attribute name="dsr-dtr" type="xs:boolean" use="optional" default="false" /> <xs:attribute name="xon-xoff" type="xs:boolean" use="optional" default="false" /> <xs:attribute name="cts-rts" type="xs:boolean" use="optional" default="false" /> <xs:attribute name="enable-dtr" type="xs:boolean" use="optional" default="false" /> <xs:attribute name="enable-rts" type="xs:boolean" use="optional" default="false" /> <xs:simpletype name="baudratetype"> <xs:restriction base="xs:nonnegativeinteger"> <xs:enumeration value="1200" /> <xs:enumeration value="2400" /> <xs:enumeration value="4800" /> <xs:enumeration value="9600" /> <xs:enumeration value="19200" /> <xs:enumeration value="38400" /> <xs:enumeration value="57600" /> <xs:enumeration value="115200" /> </xs:restriction> </xs:simpletype> <xs:simpletype name="paritybittype"> <xs:restriction base="xs:string"> <xs:enumeration value="even" /> <xs:enumeration value="mark" /> <xs:enumeration value="none" /> <xs:enumeration value="odd" /> <xs:enumeration value="space" /> </xs:restriction> </xs:simpletype> <xs:simpletype name="stopbittype"> <xs:restriction base="xs:double"> <xs:enumeration value="1" /> <xs:enumeration value="1.5" /> <xs:enumeration value="2" /> </xs:restriction> </xs:simpletype> <xs:simpletype name="bits4chartype"> <xs:restriction base="xs:short"> <xs:mininclusive value="5" /> <xs:maxinclusive value="8" /> </xs:restriction> </xs:simpletype>  BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 27 of 101

28 <xs:element name="user-io" type="self:useriotype" /> <xs:complextype name="useriotype"> <xs:choice minoccurs="0"> <xs:element name="command" type="self:conduseriocmdtype" /> <xs:element ref="setstate:u-script" /> </xs:choice> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="type" type="self:dirtype" use="optional" default="io" />  <xs:simpletype name="dirtype"> <xs:restriction base="xs:string"> <xs:enumeration value="i" /> <xs:enumeration value="o" /> <xs:enumeration value="io" /> </xs:restriction> </xs:simpletype>  <xs:element name="server" type="self:servertype" /> <xs:complextype name="servertype"> <xs:sequence> <xs:element name="awake" minoccurs="0" maxoccurs="1" > <xs:complextype mixed='true'> <xs:sequence>  <xs:any namespace="##any" processcontents="skip" minoccurs="0" maxoccurs="1" />  <xs:attribute name="method" type="xs:string" use="required" />  <xs:attribute name="timeout" type="xs:nonnegativeinteger" use="optional" default="300" />  <xs:attribute name="inactivity-timeout" type="xs:nonnegativeinteger" use="optional" default="300" /> </xs:element> <xs:attribute name="bridge-uri" type="self:serveruritype" use="required" /> <xs:attribute name="bridge-timeout" type="self:bridgetimeouttype" use="optional" default="300" /> <xs:attribute name="bridge-retries" type="xs:nonnegativeinteger" use="optional" BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 28 of 101

29 default="0" /> <xs:simpletype name="serveruritype"> <xs:restriction base="xs:anyuri"> </xs:restriction> </xs:simpletype> <xs:simpletype name="bridgetimeouttype"> <xs:restriction base="xs:positiveinteger"> <xs:mininclusive value="60" /> </xs:restriction> </xs:simpletype>  <xs:complextype name="connectedeventstype"> <xs:sequence> <xs:element name="history-def" type="self:historydeftype" minoccurs="0" maxoccurs="1"/> <xs:element name="conditions-def" type="self:conditionsdeftype" minoccurs="0" maxoccurs="1"/> <xs:complextype name="detachedeventstype"> <xs:sequence> <xs:element name="history-def" type="self:historydeftype" minoccurs="0" maxoccurs="1"/> <xs:element name="conditions-def" type="self:conditionsdeftype" minoccurs="1" maxoccurs="1"/> <xs:complextype name="historydeftype"> <xs:sequence> <xs:sequence maxoccurs="unbounded"> <xs:choice minoccurs="1"> <xs:element ref="getstate:getstate" /> <xs:element ref="setstate:setstate" /> </xs:choice> <xs:element name="event-triggers" minoccurs="1" maxoccurs="1" > <xs:complextype> <xs:sequence> <xs:choice minoccurs="1"> <xs:element name="on-delay" type="xs:nonnegativeinteger" minoccurs="0" maxoccurs="1" /> <xs:element name="daily" minoccurs="0" maxoccurs="1" > <xs:complextype> <xs:sequence> <xs:element name="at" type="xs:time" minoccurs="1" maxoccurs="unbounded" /> </xs:element> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 29 of 101

30 <xs:element name="weekly" minoccurs="0" maxoccurs="1" > <xs:complextype> <xs:sequence> <xs:element name="when" minoccurs="1" maxoccurs="unbounded"> <xs:complextype> <xs:attribute name="weekday" type="self:weekdaytype" /> <xs:attribute name="at" type="xs:time" /> </xs:element> </xs:element> <xs:element name="monthly" minoccurs="0" maxoccurs="1" > <xs:complextype> <xs:sequence> <xs:element name="when" minoccurs="1" maxoccurs="unbounded"> <xs:complextype> <xs:attribute name="monthday" type="self:monthdaytype" /> <xs:attribute name="at" type="xs:time" /> </xs:element> </xs:element> <xs:element name="yearly" minoccurs="0" maxoccurs="1" > <xs:complextype> <xs:sequence> <xs:element name="when" minoccurs="1" maxoccurs="unbounded"> <xs:complextype> <xs:attribute name="yearday" type="self:yeardaytype" /> <xs:attribute name="at" type="xs:time" /> </xs:element> </xs:element> </xs:choice> </xs:element> <xs:attribute name="delay" type="xs:nonnegativeinteger" use="required" /> <xs:attribute name="size" type="xs:nonnegativeinteger" use="required" /> <xs:attribute name="clean" type="xs:boolean" use="optional" default="false" />  <xs:complextype name="conditionsdeftype"> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 30 of 101

31 <xs:sequence> <xs:element ref="self:condition" minoccurs="1" maxoccurs="unbounded" /> <xs:attribute name="condition-delay" type="xs:nonnegativeinteger" use="optional" default="60" /> <xs:element name="condition" type="self:superconditiontype" /> <xs:complextype name="superconditiontype"> <xs:sequence minoccurs="0"> <xs:choice minoccurs="0" > <xs:element name="and" type="self:complexconditiontype"/> <xs:element name="or" type="self:complexconditiontype"/> <xs:group ref="self:simpleconditionset" /> </xs:choice> <xs:element ref="self:return-ports" minoccurs="0" maxoccurs="1" /> <xs:element ref="self:actions" minoccurs="0" maxoccurs="1" /> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="level" type="xs:nonnegativeinteger" use="optional" default="0" /> <xs:attribute name="condition-delay" type="xs:positiveinteger" use="optional" /> <xs:attribute name="send-history" type="xs:boolean" use="optional" default="false"/> <xs:attribute name="send-once" type="xs:boolean" use="optional" default="false"/> <xs:complextype name="complexconditiontype"> <xs:sequence maxoccurs="unbounded"> <xs:choice> <xs:element name="and" type="self:complexconditiontype"/> <xs:element name="or" type="self:complexconditiontype"/> <xs:group ref="self:simpleconditionset" /> </xs:choice> <xs:group name="simpleconditionset"> <xs:choice> <xs:element name="a-io" type="self:condaiotype" /> <xs:element name="d-io" type="self:conddiotype" /> <xs:element name="s-io" type="self:condsiotype" /> <xs:element name="user-io" type="self:conduseriotype" /> <xs:element name="time" type="self:condtimetype" /> </xs:choice> </xs:group>  <xs:complextype name="condtimetype"> <xs:sequence> <xs:choice> <xs:element name="inside" type="self:trangetype"/> <xs:element name="outside" type="self:trangetype"/> <xs:element name="eq" type="xs:time"/> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 31 of 101

32 <xs:element name="ne" type="xs:time"/> <xs:element name="ge" type="xs:time"/> <xs:element name="gt" type="xs:time"/> <xs:element name="le" type="xs:time"/> <xs:element name="lt" type="xs:time"/> </xs:choice> <xs:complextype name="trangetype"> <xs:attribute name="lower" type="xs:time" use="required" /> <xs:attribute name="upper" type="xs:time" use="required" />  <xs:complextype name="condaiotype"> <xs:choice minoccurs="1"> <xs:element name="is-error" /> <xs:element name="is-not-error" /> <xs:element name="inside" type="self:arangetype" /> <xs:element name="outside" type="self:arangetype"/> <xs:element name="eq" type="xs:double" /> <xs:element name="ne" type="xs:double" /> <xs:element name="ge" type="xs:double" /> <xs:element name="gt" type="xs:double" /> <xs:element name="le" type="xs:double" /> <xs:element name="lt" type="xs:double" /> </xs:choice> <xs:attribute name="id" type="xs:string" use="required" /> <xs:complextype name="arangetype"> <xs:attribute name="lower" type="xs:double" use="required" /> <xs:attribute name="upper" type="xs:double" use="required" /> <xs:simpletype name="aequalvaluetype"> <xs:union membertypes="xs:double"> <xs:simpletype> <xs:restriction base="xs:string" > <xs:enumeration value="error" /> </xs:restriction> </xs:simpletype> </xs:union> </xs:simpletype>  <xs:complextype name="conddiotype"> <xs:choice minoccurs="1"> <xs:element name="is-error" /> <xs:element name="is-not-error" /> <xs:element name="eq" type="xs:boolean" /> <xs:element name="ne" type="xs:boolean" /> </xs:choice> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 32 of 101

33 <xs:attribute name="id" type="xs:string" use="required" />  <xs:complextype name="condsiotype"> <xs:sequence> <xs:choice minoccurs="0"> <xs:element name="command" type="self:condserialiocmdtype" /> <xs:element ref="setstate:s-script"/> </xs:choice> <xs:element ref="self:response" minoccurs="1" maxoccurs="1" /> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="binary-result" type="xs:boolean" use="optional" default="false" /> <xs:complextype name="condserialiocmdtype"> <xs:simplecontent> <xs:extension base="xs:string"> <xs:attribute name="binary-request" type="xs:boolean" use="optional" default="false" /> <xs:attribute name="writechar-delay" type="xs:nonnegativeinteger" use="optional"/> <xs:attribute name="execution-delay" type="xs:nonnegativeinteger" use="optional" /> <xs:attribute name="at-most" type="xs:nonnegativeinteger" use="optional" /> <xs:attribute name="readchar-timeout" type="xs:nonnegativeinteger" use="optional" /> </xs:extension> </xs:simplecontent>  <xs:complextype name="conduseriotype"> <xs:sequence> <xs:choice minoccurs="0"> <xs:element name="command" type="self:conduseriocmdtype" /> <xs:element ref="setstate:u-script"/> </xs:choice> <xs:element ref="self:response" minoccurs="1" maxoccurs="1" /> <xs:attribute name="id" type="xs:string" use="required" /> <xs:attribute name="binary-result" type="xs:boolean" use="optional" default="false" /> <xs:complextype name="conduseriocmdtype"> <xs:simplecontent> <xs:extension base="xs:string"> <xs:attribute name="binary-request" type="xs:boolean" use="optional" default="false" /> </xs:extension> </xs:simplecontent> BITXml is a registered trademark of Your Voice S.p.A. Milan - Italy - Page 33 of 101

ՕՐԻՆԱԿ. <xs:schema targetnamespace=" xmlns:tax="

ՕՐԻՆԱԿ. <xs:schema targetnamespace= xmlns:tax= ՕՐԻՆԱԿ