Contact Us
Documentation

Application Note

iOn Tag Service

This application note describes the behavior and configuration of CalAmp’s iOn Tag service using CalAmp’s telematics devices and iOn Tags. When a telematics device has the tag service activated, it will continuously scan for nearby iOn Tags and maintain a list of tags that are within range. The device reports tag data to the CalAmp Telematics Cloud (CTC), where it is geotagged, associated with customer assets, and made available through APIs to end customers. Filtering options are available to specify the type of iOn Tags to be included in a telematics device’s tag list.

The solution described in this document makes use of iOn Tags. A telematics device’s PEG script participates in the reporting of the current tag list typically when tags are discovered, lost, or on an interval to keep CTC updated with tag activity.

Terms

BLE: Bluetooth low energy
CTC: CalAmp Telematics Cloud
OUI: Organizationally unique identifier
UUID: Universally unique identifier

Use Cases

Tags Attached to Tools or Small Assets

  • Tools left behind at a job site
  • Tool usage on a job site
  • Truck association for tools
  • Location history for tools

iOn Tag Service Operation

When the tag service is activated on a telematics device, it will start scanning BLE channels for nearby tags. The telematics device maintain a list of tag IDs so that it can determine if a tag has been discovered or lost.

A telematics device will add a tag to the list in these circumstances:

  • The tag ID passes tag filtering of allowed tags.
  • The tag is within BLE range with a stronger RSSI than the tag-detection RSSI threshold.

A tag will be removed from the telematics device's list if the device stops receiving data from the tag for a period exceeding the asset time-out time.

The telematics device periodically reviews the list (according to the time set in the tag list trigger interval) and does the following:

  • Generates a tag-detected PEG trigger if any tags were added to the list since the last review.
  • Generates a tag-lost PEG trigger if any tags have aged out since the last review. Those tags are removed from the list.
  • Checks for tags within BLE range with a stronger RSSI than the tag-detection RSSI threshold.

The telematics device's tag list and associated tag data are sent as telematics device gateway events, which will only be sent to CTC servers. The PEG script controls when gateway events are generated for CTC so that they can be sent on an interval, when the tag list changes, or due to any other PEG trigger.

iOn Tags

Tag Types
PTAG04: Proximity tag
STAG04HT: Humidity and temperature tag

473

Specifications

Lifetime
PTAG04: 2 years (under normal conditions)
STAG04HT: 9 months (under normal conditions)

Range: Up to 80 meters line of sight

Tag ID Conversion
72057594037927936: Scanned from SCI tag label
00E4509A1D0A89: Converted to hex
E4509A1D0A89: ID (MAC address) as seen in telematics device debug with the first three digits removed

Telematics Device Configuration

Bluetooth Parameters
BLE Asset Timeout Time — parameter 3840: The time in seconds that a tag needs to be out of BLE range before it is removed from the telematics device’s tag list.
Default value: 60 seconds
Example: at$app param 3840,0,60

Tag Parameters
BLE Asset Tag Trigger Interval — parameter 3841: The periodic interval in seconds that the telematics device reviews the list to generate triggers and remove aged-out tags from the list.
Default value: 8 seconds
Example: at$app param 3841,0,8

iOn Tag Detection RSSI Threshold — parameter 3842 (signed byte): Used to set the BLE Asset Tag Service RSSI threshold, in dBm.
Index 1: Lower threshold. If RSSI drops below this level, tags are deleted from the tracking list. This threshold is disabled if the value is greater than the value in index 0.
Default value: -128 dBm
Example: at$app param 3842,0,-128

NOTE: Because this parameter is a signed byte (2’s complement), a value of -128 is displayed on a parameter query as 128. -60 shows as 196.

iOn Tag Filtering — parameter 3843: Defines a list of OUIs that is used to filter which iOn Tag IDs can be added to the tag list.
The OUI value is the first three bytes of the tag’s ID (MAC address) and is formatted as three comma-separated decimal bytes per index.
Eight total indexes (0-7) are available for filtering.
Default value: Index 0 = 228,80,154 (SCI tag OUI)
Example to filter for only iOn Tags:
Tag ID (MAC address): 0xE4509A1D0A89
0xE4 = 228 , 0x50 = 80 , 0x9A = 154
at$app param 3843,0,228,80,154

PEG Triggers
iOn Tag Trigger: PEG trigger 105.
Modifier 0: One or more tags have been removed from the tag list.
Modifier 1: One or more tags have been added to the tag list.

PEG Actions
Send iOn Tag Report: PEG action 163
Modifier 0: Sends the verbose tag list with the full payload, MAC address, RSSI, and time.
Modifier 1: Sends the concise tag list with the MAC address, RSSI, and time.

Telematics Device Debug
You can view tag IDs and RSSI values for surrounding tags in the telematics device debug stream. To enable iOn Tag debug, set bit 4 of s-register 126. The generic debug must also be enabled in s-register 125, and you can adjust the amount of tag information shown:

  • ats125=3: Shows iOn Tag data for tags that have passed tag filtering.
  • ats125=5: Shows all BLE packets received from devices in the area.

CalAmp Telematics Cloud

The gateway events from telematics devices are sent to CTC, where they are processed into individual tag reports. Gateway events and tag reports are provided as JSON objects and are available through multiple CTC services, including these:

  • Data Pump: Offers a real-time queue of events from all the devices in an account.
  • Results Services: Provides historical data for telematics devices and tags.
  • Entity Services: Enables you to configure alerts.

Endpoints for CTC APIs
CTC has two production environments, CTC US and CTC UK. The following API examples show URLs for CTC US. If the devices are pointed to CTC UK, change ".com" to ".co.uk" in the base URL.

Data Pump
Data Pump is a queue of event messages from the devices in the CTC account, and each CTC user has their own independent Data Pump queue. As messages are requested through the Data Pump service, they are removed from the queue using a first-in-first-out (FIFO) method. Data Pump can provide the count of pending events, and events can be requested directly. You can request up to 100 messages in a single response.

To request data from Data Pump, follow these steps:

  1. Authenticate with the CTC server using your CTC credentials.
  2. Collect the authToken from the authentication response.
  3. Request data from Data Pump using the authToken.

Authentication
Post to URL: https://connect.calamp.com/connect/services/login
Parameters
useAuthToken: True
Username: (username of CTC user)
Password: (password for CTC user)

A successful authentication response will include the authToken cookie, which is then used to get the Data Pump count or event requests. The token will remain active 30 minutes after the last API activity. If the authtoken expires, you can repeat the authentication process to get a new authToken.

Data Pump Event Count
Get to URL: https://connect.calamp.com/connect/datapump/services/events/count
Parameters
calamp-services-app: The authorization token obtained from the authorization call

Data Pump Events
Get to URL: https://connect.calamp.com/connect/datapump/services/events
Parameters
calamp-services-app: The token from authentication

Data Pump JSON responses include a header with a count for each message type included.

496

Results Services
Results Services provide a historical log of the events from telematics devices or iOn Tags.

URL: [ /connect/results/events/device/] (/connect/results/events/device/)
Authentication: Basic authorization using CTC credentials

Results Services offer many options for pulling data, including the following: (See the Results Services section of the API documentation for a complete listing of the available APIs.)

  • Get the latest events from a telematics device or iOn Tag
  • Get a specific event by UUID
  • Get events by time frame
  • Get the location history of a tag

CTC Event Data Structure

Telematics Device Gateway Event
This includes location data for the telematics device gateway, a tag list, and all the iOn Tag reports.

Tag Reports

A tag report contains tag information from an individual tag.

Reference Links

Telematics device firmware release notes: https://puls.calamp.com/wiki/Release_Notes_TELEMATICS_DEVICE32

NOTE: You'll need to have a PULS login to access these release notes.

CTC API documentation: https://connect.calamp.com/connect

Updated about 2 years ago

© 2023 CalAmp