How to start with Sigfox Atlas?

Design or choose a device

First, if you are looking for an existing solution, you should choose one in the Partner Network.

If you want to design your own device, you must - first of all - identify the right location technology(ies) for the use case (GPS, WiFi, Sigfox Network only, etc). The 2 questions below (to ask to yourself or your user) should help you to define the right solution:

1. In which kind of environment(s) do you need to geolocate these assets ? 

  • Outdoors, in rural or (far) remote areas > you'll need a long range geolocation solution, such as GPS and/or the Sigfox Network location.
  • Outdoors, in urban or industrial areas > you'll need a technology suitable for dense environments, such as WiFi.
  • Indoors, in public space/ venues (airports, shopping mall, etc) > the WiFi is also the most suitable for these areas - RTLS can be also depending on your capacity to deploy an infrastructure in these sites.
  • Indoors, in your private premises (your factory or building) > WiFi or RTLS solutions can work.
  • Indoors, in private premises which are not yours (your customer or supplier factory or building) > WiFi or RTLS solutions, depending on your capacity to deploy an infrastructure in these sites.

2. What is the level of precision that you need? 

  • City level > the Sigfox Network location is enough.
  • Premise/ venue level > the WiFi is enough.
  • Within a premise/ venue level > the RTLS solutions works well on that case.

If the Sigfox Network location and/or WiFi Positioning match with your use case, you can go with Atlas services:

  • If Atlas Native fits with your use case, you don’t need to do anything on the device side. 
  • If you choose Atlas WiFi, you'll find below the guidelines for the hardware and protocol for the payload format.


Guidelines for WiFi device hardware  

The device hardware must embed at least Sigfox and WiFi chipset or modules. Some guidelines regarding the WiFi component: 

  • It is better to implement a WiFi chipset or module compatible with our WiFi protocol specification to increase the chance to collect (or sniff) MAC@.  
  • If the device only uses WiFi chipset in sniffing mode (Rx only), there will be no need for TA certification.  
  • WiFi antenna performance is critical and will have a high impact on the chance to sniff MAC@.
  • For devices using modules already embedding a WiFi antenna, it is important to follow the module implementation guidelines to maximize the device radiated performance. 
  • For devices with a dedicated antenna implementation, it is important to design the antenna with care and to check that the device radiated performance are high enough.  

  

Specification for WiFi device payload format

The device firmware should integrate the payload encoding specification and format for WiFi:

1. Collect MAC@

[SyRS_WIFILOC_001] Device shall be able to sniff all WIFI access points around it and collect the MAC address of each WIFI access point detected.

[SyRS_WIFILOC_002] Device MUST collect MAC addresses which: 

  • Are from beacon frames or probe response frames (only Wifi Access Point mac address MUST be returned).
  • Are not part of an ad hoc Wifi network.
  • Are of type "Unicast" (LSB bit of 1st byte MUST be 0).
  • Are not a reserved mac address: 00:00:00:00:00:00, FF:FF:FF:FF:FF:FF, … 

[SyRS_WIFILOC_003] Device MUST select up to two MAC addresses by filtering and prioritizing them according to rules. There are no global absolute rules which fit all business cases, so rules should be set and executed according to the forecasted devices business case. It is recommended that rules priorities and rules execution flag can be set through a configuration downlink message. 

By default, to maximize the WIFI location success rate, the following rules are recommended (by decreasing priority order):

  • MAC address of type globally unique (second bit of 1st byte is 0 - see Figure 3‑3: MAC Address Format)
  • Do not correspond to a mobile access point: exclude SSID containing "android", "phone", "samsung", "huawei" (case insensitive comparison). List is not exhaustive, and MUST be adapted to countries deployed
  • Have not an empty SSID.
  • MAC address with the strongest RSSI. 

Other custom rules which could be implemented are for instance:

  • SSID in a custom whitelist or matching a pattern
  • SSID not in a custom blacklist, or not matching a pattern
  • Other condition on the SSID
  • Other condition on the mac@ (specific OUI preferred, etc...)

As only 2 MAC addresses are used, the selection of the proper ones is critical to obtain the maximum success for the mac address geolocation resolution.

 2. Serialize and send WIFI location payload

[SyRS_WIFILOC_004] WIFI location messages shall be sent in UPLINK message of U-Procedure (Unidirectional Procedure – UL) or B-Procedure (Bidirectional Procedure). 

[SyRS_WIFILOC_005] Device shall send up to two MAC addresses selected according criteria defined above in 12-byte payload and shall comply with the format defined in Figure 3‑4: Wifi Location Payload Format:

  • Parameter 1: MAC address 1
  • Parameter 2: MAC address 2

[SyRS_WIFILOC_006] If only one MAC address corresponding to the criteria defined in sub-section 3.1 is sniffed by the device, the MAC address shall be sent in the first parameter of WIFI payload, the second one shall be NULL (00:00:00:00:00:00). 

[SyRS_ATLASWIFI_007] (deprecated, replaced by SyRS_WIFILOC_008) 12-Byte payload shall be not used by Device to send other type of data. 12-Byte payload is reserved to transmit ATLAS WIFI payload.

[SyRS_WIFILOC_008] For a device which has the WIFI location service provisioned, 12 Byte payload will be interpreted by Sigfox cloud according to the values of the 2 1st bits (LSB) of the 1st byte.
NB: this is not a distinct header field, as for a Wifi payload these 2 bits are part of the 1st MAC address.

Activate Atlas

The provisioning of both Atlas services must be done in the contract before its activation on the Sigfox Cloud portal (back end). 

Follow these steps to provision Atlas services on a new contract: 

  • Open the order   
  • Click on [Create Contract] 
  • Enter a name for the contract 
  • Select the correct client 
  • Optional: decide whether you want to set an end date for the contract 
  • Optional: decide whether you want to restrict the number of tokens applicable to the contract  
  • Select “Atlas Native” or “Atlas WiFi” (available on January 1st 2020) 
  • Save the contract. 

Once the Atlas service has been provision in your contract, you just need to follow the same steps than for the activation of your tokens in the back end. The availability of Atlas is mentioned in the Device Type section (“geoloc : yes”).


Retrieve location information

Through the Data Advanced Callback

The location information delivered by both Atlas Native & Atlas WiFi are provided through the Data advanced service callback to the customer IT system consecutively to the reception of a new message. 

The Data advanced service callback contains the following information: 

· Device ID 

· Message sequence number 

· Message timestamp (corresponding to the same timestamp as the data callback) 

· Link Quality Indicator. 

· Territory of usage. 

· Network metadata and duplicates (on contract option).  

· Computed geolocation:  

  • Source (Network location or WiFi location)
  • Position longitude 
  • Position latitude 
  • Position radius 

The location data is stored as metadata in the Sigfox infrastructure associated with the message. This information is used to provide the location on API call. If the location information has not been successfully defined by the Geomodule, no Data Advanced service callback is generated (except if the payload has been “activated” in the Data advanced service callback) and no location information is stored with the message as metadata.

Through API

This method allows the customer system to request the current location of a device through the Sigfox infrastructure API. This information is available through different APIs:

· The “device message” API, provides the last messages’ computed locations (latitude, longitude & radius). The caller is able to define the number of messages to take into account in the history such as the last 10 messages.

  • Endpoint1: GET/devices/{id}/messages 

· The “device location” API provides the same feature as the API “device message.”

  • Endpoint2: GET/devices/{id}/locations 

· The “device information” API provides only the last message’s computed location and not that of several. It also provides the customer reported location during the device activation process.

If GPS information is available in the payload, the location is provided with a radius equal to 0. If the location has not been evaluated by the Geomodule during the reception of the message, no location is provided.