Difference between revisions of "SIGFOX"

From HSYCO
Jump to navigation Jump to search
 
(87 intermediate revisions by 3 users not shown)
Line 24: Line 24:
 
E.g.  
 
E.g.  
  
−
<pre>BE1234:name=homesensor,model=eccoswitch</pre>
+
<pre>BE1234:name=homesensor,model=AlarmHubBase</pre>
−
<pre>BE1234:model=eccoswitch,name=homesensor</pre>
+
<pre>BE1234:model=AlarmHubBase,name=homesensor</pre>
 
<pre>BE1234:name=homesensor</pre>
 
<pre>BE1234:name=homesensor</pre>
−
<pre>BE1234:model=eccoswitch</pre>
+
<pre>BE1234:model=AlarmHubBase</pre>
 
<pre>BE1234</pre>
 
<pre>BE1234</pre>
  
  
 
Device id must be present in each line while name and model are optional. Device identifiers are considered as case insensitive by the SIGFOX I/O Server, so there can't be two identifiers with the same sequence of characters in upper/lower case, e.g. "BE1234" and "be1234" are considered the same.
 
Device id must be present in each line while name and model are optional. Device identifiers are considered as case insensitive by the SIGFOX I/O Server, so there can't be two identifiers with the same sequence of characters in upper/lower case, e.g. "BE1234" and "be1234" are considered the same.
−
 
−
=== Message types ===
 
−
To retrieve messages from Sigfox Cloud you can use API and/or callbacks.
 
−
 
−
==== API ====
 
−
In order to use API you have to set User and Password
 
  
 
=== Options ===
 
=== Options ===
Line 70: Line 64:
  
 
|callbackport
 
|callbackport
−
|
+
|4445
 
|<portNumber>
 
|<portNumber>
 
|internal port used to receive incoming callback messages from Sigfox Cloud
 
|internal port used to receive incoming callback messages from Sigfox Cloud
Line 80: Line 74:
 
|<text>
 
|<text>
 
|key used in Sigfox URL callbacks to receive incoming callback messages
 
|key used in Sigfox URL callbacks to receive incoming callback messages
 +
 +
|-
 +
 +
|callbackiprange
 +
|
 +
|<text>
 +
|Trusted nets that can be accepted as callbacks, if you dont set up this field the callback feature will be NOT active
  
 
|-
 
|-
  
 
|pollinterval
 
|pollinterval
−
|
+
|15000
 
|1000<n<30000
 
|1000<n<30000
−
|interval (in milliseconds) between two consecutive HTTP calls at Sigfox Cloud (only for API)
+
|interval (in milliseconds) between two consecutive HTTP calls to Sigfox Cloud (only for API)
 +
 
 +
|}
 +
 
 +
=== Device Messages ===
 +
To retrieve device messages from Sigfox Cloud you can use API and/or callbacks. API are easier to set up but they require to wait for an interval to expire (max 30 seconds) to get every new message sent by devices to Sigfox Cloud. Callbacks are a little bit tricky to set up but they allow to retrieve every new message sent by devices as soon as Sigfox Cloud receives it.
 +
 
 +
==== API ====
 +
In order to use Sigfox API you have to create an API user in Sigfox backend (unless you already have an existing one), then use the newly API user credentials to set '''User''' and '''Password''' in SIGFOX I/O Server configuration.
 +
 
 +
==== Callbacks ====
 +
In order to use Sigfox callback services you must have a public IP address, have the Sigfox api ipaddress in the callbackiprange you can find the static IP of Sigfox [https://support.sigfox.com/docs/callback-integration here] (as of 28/09/2022 the Sigfox ip range is 185.110.96.1 to 185.110.99.254 so in the callbackiprange you should have 185.110.96.1-185.110.99.254) and you also need to configure your router ports to let outside traffic to get into your network to your Hsyco. You also have to set '''callbackkey''' option and '''callbackport''' option (if the default 4445 is already in use or if you are using more instances of SIGFOX driver) in SIGFOX I/O Server options.
 +
 
 +
Every time Sigfox Cloud receive a message from a device it immediately propagates it to your SIGFOX driver, filling all message informations into an URL. Callback messages must be configured in Sigfox backend (you can configure callbacks for each device type associated to your account) choosing channel "URL" and composing the URL in the following format:
 +
 
 +
<pre>http://<public_ip_address>:<port>/hsyco/sigfox/<I/O_server_name>?key=<callbackkey>&id={device}&field1={var1}&field2={var2}&field3={var3}...</pre>
 +
 
 +
<port> is the public port opened on your router, <callbackkey> corresponds to '''callbackkey''' option of SIGFOX I/O Server. The URL fields "key" and "id" must be always present. The URL fields "field1", "field2", "field3", etc.. are optionals and can be set accordingly to the type of callback you are configuring in Sigfox backend; fields order is irrelevant. URL fields must be separated with '&' character.
 +
 
 +
E.g.
 +
 
 +
<pre>http://93.45.12.54:7777/hsyco/sigfox/sgfx?key=Abc1234&id={device}&time={time}&data={data}&seqNumber={seqNumber}</pre>
 +
 
 +
Below are reported all URL fields that SIGFOX driver can process:
 +
 
 +
{| class="wikitable"
 +
!ID
 +
!Description
 +
 
 +
|-
 +
 
 +
|id
 +
|device ID
 +
 
 +
|-
 +
 
 +
|time
 +
|timestamp (in Epoch time) of the message
 +
 
 +
|-
 +
 
 +
|data
 +
|message content
 +
 
 +
|-
 +
 
 +
|seqNumber
 +
|sequential number of the message
 +
 
 +
|-
 +
 
 +
|batt
 +
|device battery voltage
 +
 
 +
|-
 +
 
 +
|temp
 +
|device temperature (C˚)
 +
 
 +
|-
 +
 
 +
|lqi
 +
|link quality indicator (as reported in Datapoints section)
 +
 
 +
|-
 +
 
 +
|deviceTypeId
 +
|the ID of the device type in which this device is grouped
 +
 
 +
|}
 +
 
 +
=== Device Models ===
 +
You can assign a model to each of your devices by modifying directly the file "sigfox-devices_&#60;I/O_Server_name&#62;.ini" (as described above) or using the [[SIGFOX Utility]]. By assigning a model to a device the SIGFOX driver can decode raw messages coming from that device accordingly to its communication protocol, this will generate more informations and relatives datapoints.
 +
 
 +
Actually the only device model supported by SIGFOX driver is the sequent:
 +
 
 +
{| class="wikitable"
 +
!ID
 +
!Protocol
 +
 
 +
|-
 +
 
 +
|AlarmHubBase
 +
|Ecco Switch protocol firmware V2
 +
 
 +
|-
 +
 
 +
|AlarmHubStatus
 +
|Ecco Switch protocol firmware V3
  
 
|}
 
|}
Line 146: Line 235:
 
|<text>
 
|<text>
 
|R
 
|R
−
|last message sent by deviceId (Hexadecimal format)
+
|content of the last message sent by deviceId
  
 
|-
 
|-
Line 194: Line 283:
 
|R
 
|R
 
|internal temperature (C˚) of deviceId
 
|internal temperature (C˚) of deviceId
 +
 +
|}
 +
 +
=== AlarmHubBase ===
 +
 +
Below are reported all datapoints generated from incoming messages from '''AlarmHubBase''' model devices. Those datapoints are in addition to SIGFOX I/O Server standard datapoints.
 +
 +
{| class="wikitable"
 +
!ID
 +
!Value
 +
!R/W
 +
!Description
 +
 +
|-
 +
 +
|rowspan="2" |device.<deviceId>.msg.test
 +
|1
 +
|R
 +
|status change on button "test" of deviceId
 +
|-
 +
|0
 +
|R
 +
|no status change on button "test" of deviceId
 +
 +
|-
 +
 +
|rowspan="2" |device.<deviceId>.msg.in.<n>
 +
|1
 +
|R
 +
|status change on input <n> of deviceId
 +
|-
 +
|0
 +
|R
 +
|no status change on input <n> of deviceId
 +
 +
|-
 +
 +
|device.<deviceId>.batt.idle
 +
|<val>
 +
|R
 +
|battery voltage (in idle state) of deviceId
 +
 +
|}
 +
 +
 +
=== AlarmHubStatus ===
 +
 +
Below are reported all datapoints generated from incoming messages from '''AlarmHubStatus''' model devices. Those datapoints are in addition to SIGFOX I/O Server standard datapoints.
 +
 +
{| class="wikitable"
 +
!ID
 +
!Value
 +
!R/W
 +
!Description
 +
 +
|-
 +
 +
|rowspan="2" |device.<deviceId>.msg.test
 +
|1
 +
|R
 +
|status change on button "test" of deviceId
 +
|-
 +
|0
 +
|R
 +
|no status change on button "test" of deviceId
 +
 +
|-
 +
 +
|rowspan="2" |device.<deviceId>.msg.in.<n>
 +
|1
 +
|R
 +
|status change on input <n> of deviceId
 +
|-
 +
|0
 +
|R
 +
|no status change on input <n> of deviceId
 +
 +
|-
 +
 +
|device.<deviceId>.batt.idle
 +
|<val>
 +
|R
 +
|battery voltage (in idle state) of deviceId
 +
 +
|-
 +
 +
|rowspan="2" |device.<deviceId>.in.<n>.status
 +
|1
 +
|R
 +
|input <n> of deviceId is active
 +
|-
 +
|0
 +
|R
 +
|input <n> of deviceId is not active
  
 
|}
 
|}
Line 201: Line 384:
 
=== 3.8.0 ===
 
=== 3.8.0 ===
 
*initial release
 
*initial release
 +
 +
----
 +
''Sigfox is a registered trademark of Sigfox S.A.''

Latest revision as of 15:24, 28 September 2022

Sigfox is a global network operator founded that builds wireless networks to connect low-power objects such as electricity meters and smartwatches, which need to be continuously on and emitting small amounts of data. This driver allows you to communicate with Sigfox Cloud in order to retrieve messages and status updates collected from devices. As reported in the Sigfox backend, each device is grouped into a device type.

HSYCO Configuration

Add the SIGFOX I/O Server in the I/O Servers section of the Settings and set its parameters:

Authentication

  • User: optional API username
  • Password: optional API password

Devices list file

At the first run of SIGFOX driver a file named "sigfox-devices_<I/O_Server_name>.ini" will be created . This file can contain a series of line, each line represents informations of a single device and can have the following format: 

<device_id>:name=<device_name>,model=<device_model>
<device_id>:model=<device_model>,name=<device_name>
<device_id>:name=<device_name>
<device_id>:model=<device_model>
<device_id>

E.g. 

BE1234:name=homesensor,model=AlarmHubBase
BE1234:model=AlarmHubBase,name=homesensor
BE1234:name=homesensor
BE1234:model=AlarmHubBase
BE1234


Device id must be present in each line while name and model are optional. Device identifiers are considered as case insensitive by the SIGFOX I/O Server, so there can't be two identifiers with the same sequence of characters in upper/lower case, e.g. "BE1234" and "be1234" are considered the same.

Options

ID Default Values Description
startupevents true true generate IO events also during the driver’s start-up phase
false start generating events only after HSYCO is aligned with the current status of the system
acceptunknown false true accept incoming messages from devices whose id isn't specified in sigfox-devices.ini
false doesn't accept incoming messages from devices whose id isn't specified in sigfox-devices.ini
callbackport 4445 <portNumber> internal port used to receive incoming callback messages from Sigfox Cloud
callbackkey <text> key used in Sigfox URL callbacks to receive incoming callback messages
callbackiprange <text> Trusted nets that can be accepted as callbacks, if you dont set up this field the callback feature will be NOT active
pollinterval 15000 1000<n<30000 interval (in milliseconds) between two consecutive HTTP calls to Sigfox Cloud (only for API)

Device Messages

To retrieve device messages from Sigfox Cloud you can use API and/or callbacks. API are easier to set up but they require to wait for an interval to expire (max 30 seconds) to get every new message sent by devices to Sigfox Cloud. Callbacks are a little bit tricky to set up but they allow to retrieve every new message sent by devices as soon as Sigfox Cloud receives it.

API

In order to use Sigfox API you have to create an API user in Sigfox backend (unless you already have an existing one), then use the newly API user credentials to set User and Password in SIGFOX I/O Server configuration.

Callbacks

In order to use Sigfox callback services you must have a public IP address, have the Sigfox api ipaddress in the callbackiprange you can find the static IP of Sigfox here (as of 28/09/2022 the Sigfox ip range is 185.110.96.1 to 185.110.99.254 so in the callbackiprange you should have 185.110.96.1-185.110.99.254) and you also need to configure your router ports to let outside traffic to get into your network to your Hsyco. You also have to set callbackkey option and callbackport option (if the default 4445 is already in use or if you are using more instances of SIGFOX driver) in SIGFOX I/O Server options.

Every time Sigfox Cloud receive a message from a device it immediately propagates it to your SIGFOX driver, filling all message informations into an URL. Callback messages must be configured in Sigfox backend (you can configure callbacks for each device type associated to your account) choosing channel "URL" and composing the URL in the following format: 

http://<public_ip_address>:<port>/hsyco/sigfox/<I/O_server_name>?key=<callbackkey>&id={device}&field1={var1}&field2={var2}&field3={var3}...

<port> is the public port opened on your router, <callbackkey> corresponds to callbackkey option of SIGFOX I/O Server. The URL fields "key" and "id" must be always present. The URL fields "field1", "field2", "field3", etc.. are optionals and can be set accordingly to the type of callback you are configuring in Sigfox backend; fields order is irrelevant. URL fields must be separated with '&' character.

E.g. 

http://93.45.12.54:7777/hsyco/sigfox/sgfx?key=Abc1234&id={device}&time={time}&data={data}&seqNumber={seqNumber}

Below are reported all URL fields that SIGFOX driver can process:

ID Description
id device ID
time timestamp (in Epoch time) of the message
data message content
seqNumber sequential number of the message
batt device battery voltage
temp device temperature (C˚)
lqi link quality indicator (as reported in Datapoints section)
deviceTypeId the ID of the device type in which this device is grouped

Device Models

You can assign a model to each of your devices by modifying directly the file "sigfox-devices_<I/O_Server_name>.ini" (as described above) or using the SIGFOX Utility. By assigning a model to a device the SIGFOX driver can decode raw messages coming from that device accordingly to its communication protocol, this will generate more informations and relatives datapoints.

Actually the only device model supported by SIGFOX driver is the sequent:

ID Protocol
AlarmHubBase Ecco Switch protocol firmware V2
AlarmHubStatus Ecco Switch protocol firmware V3

SIGFOX Utility

Use the SIGFOX Utility to automatically discover new devices or configure existing ones.

Datapoints

ID Value R/W Description
connection online R the driver is ready to accept incoming messages from Sigfox Cloud
offline R initialization of the driver failed or loop cycle failed
devicetype.<devicetypeId>.name <text> R the name of the device type corresponding to devicetypeId (only obtainable with API)
device.<deviceId>.devicetype <text> R the ID of the device type in which deviceId is grouped
device.<deviceId>.name <text> R the name of deviceId (only obtainable with API)
device.<deviceId>.lastseen <ts> R timestamp (in Epoch time) of the last message sent by deviceId
device.<deviceId>.msg <text> R content of the last message sent by deviceId
device.<deviceId>.token.end <ts> R deviceId token end date (in Epoch time) (only obtainable with API)
device.<deviceId>.lqi 0 R link quality indicator (computed from the last message received by Sigfox Cloud). 0=limit, 1=average, 2=good, 3=excellent, 4=not available
1 R
2 R
3 R
4 R
device.<deviceId>.batt.tx <val> R battery voltage (during transmission) of deviceId
device.<deviceId>.batt.idle <val> R battery voltage (in idle state) of deviceId
device.<deviceId>.temp <val> R internal temperature (C˚) of deviceId

AlarmHubBase

Below are reported all datapoints generated from incoming messages from AlarmHubBase model devices. Those datapoints are in addition to SIGFOX I/O Server standard datapoints.

ID Value R/W Description
device.<deviceId>.msg.test 1 R status change on button "test" of deviceId
0 R no status change on button "test" of deviceId
device.<deviceId>.msg.in.<n> 1 R status change on input <n> of deviceId
0 R no status change on input <n> of deviceId
device.<deviceId>.batt.idle <val> R battery voltage (in idle state) of deviceId


AlarmHubStatus

Below are reported all datapoints generated from incoming messages from AlarmHubStatus model devices. Those datapoints are in addition to SIGFOX I/O Server standard datapoints.

ID Value R/W Description
device.<deviceId>.msg.test 1 R status change on button "test" of deviceId
0 R no status change on button "test" of deviceId
device.<deviceId>.msg.in.<n> 1 R status change on input <n> of deviceId
0 R no status change on input <n> of deviceId
device.<deviceId>.batt.idle <val> R battery voltage (in idle state) of deviceId
device.<deviceId>.in.<n>.status 1 R input <n> of deviceId is active
0 R input <n> of deviceId is not active

Release Notes

3.8.0

  • initial release

Sigfox is a registered trademark of Sigfox S.A.

Retrieved from "https://wiki.hsyco.com/3.8/index.php?title=SIGFOX&oldid=10764"