Getting Started with Locus: Setup Requirements

This checklist outlines the essential hardware, network, and configuration requirements to successfully set up and start using the Locus application for asset tracking. Ensure all prerequisites are met to enable seamless integration and accurate tracking across your sites, buildings, and floor plans.

A LoRaWAN Network Server must be selected and integrated with Locus.

Ensure the NS account has at least one gateway online and existing device entities.

Example: NS account with gateway “Gateway1” online and devices like “TEKTELIC Pelican” provisioned.

For any questions regarding TEKTELIC Network Server, please follow KONA Core Network Server Guide

• Access the TEKTELIC NS dashboard and navigate to the “Data Converters” section.
• Create a new converter named “LocusDataConverter”.
• Decoder:

// input object structure:
// - bytes - int[]
// - fPort - int
// - recvTime - Date (needs type check)
// - tektelicMetadata - Object
if (input.recvTime instanceof Date) {
    // date operations
}
// output object structure:
// - data - Object
// - errors - string[]
// - warnings - string[]
// - tektelicMetadata - Object
return {
    "data": {
        "bytes": input.bytes
    },
    "errors": [],
    "warnings": [],
    "tektelicMetadata": input.tektelicMetadata
};

• Encoder:

// input object structure:
//  - data - Object (customer-defined)
// output object structure:
// - fPort - int
// - bytes - int[]
// - errors - string[]
// - warnings - string[]
    return {
    "fPort": input.data.fPort,
    "bytes": input.data.bytes,
    "errors": [],
    "warnings": []
};

• Save the converter.

• Navigate to the “Applications” section in the TEKTELIC NS dashboard.

• Select an application with devices, that will be used with Locus.

• Open “Integrations” section.

• Add a new integration with the following settings:

  • Name: “Locus_Integration”.

  • Type: HTTPv2.

  • Data Converter: Select “Locus_Data_Converter”.

  • Application Address: Contact the development team for the tenant-specific URL.

  • Port: 443.

  • Base Path: /v2/integration.

  • HTTPS: Enabled.

  • Request Headers

    Key: ApiKey

    Value: ApiKey

• Configure Data Converter:

  • Access your 3rd party NS dashboard and locate the section for custom data converters (e.g., “Functions” or “Scripts”).

  • Create a new converter named “LocusDataConverter”.

  • Use the same decoder and encoder scripts as above.

  • Save the converter and associate it with your application.

  • Integration Setup:

    • Navigate to the integrations section in your 3rd party NS dashboard.
    • Add a new integration with the same settings as for TEKTELIC NS:

      • Name: “Locus_Integration”.

      • Type: HTTPv2 (or equivalent, depending on NS).

      • Data Converter: Select “Locus_Data_Converter”.

      • Application Address: Contact the development team for the tenant-specific URL.

      • Port: 443.

      • Base Path: /v2/integration.

      • HTTPS: Enabled.

      • Request Headers:

        Key: ApiKey
        Value: ApiKey

  • Test the integration to ensure data is transmitted to Locus.

  • Note: Some 3rd party NS may require additional configuration (e.g., custom endpoints or authentication methods). Refer to your NS documentation.

• Gateways to be used must be provisioned on the LoRaWAN Network Server (NS).
• Ensure the gateway`s status is online on the NS.
• Example: Gateway “TEKTELIC KONA Macro” provisioned on the NS and online.

• Devices to be used must be provisioned on the Network Server.
• Devices to be used must be put in the application on the Network Server that has an integration with Locus application.
• Provide either the T-code, Serial Number, Revision, or DevEUI for each device (e.g., T-code “T0007127”/Revision “A1”/Serial Number “2020A0101” or DevEUI: “647FDA000001F136” ).
• Example: Device “TEKTELIC Pelican” with DevEUI “647FDA000001F136” or T-code “T0007127”/Revision “A1”/Serial Number “2020A0101”.

• Site Details (required for both indoor/outdoor tracking):

  • Site Name: Provide the name of the site (e.g., “Madrid”).
  • Site Address: Specify the address for accurate map placement (e.g., “C. del Bonetillo, 10, Centro, 28013 Madrid”).

• Building Details (required only for indoor tracking):

  • Building Name: Provide the name of the building (e.g., “Building2”).
  • Building Address: Specify the address for accurate map pinning (e.g., “C. del Bonetillo, 10, Centro, 28013 Madrid”).

• Floor Plan Details (required only for indoor tracking):

  • Floor Plan Image: Provide an image of the floor plan without whitespaces for precise tracking (supported formats: .jpg, .jpeg, .png; max size: 2MB).
  • Floor Plan Size: Specify dimensions in meters. Floor plan dimension should be accurate according to it’s engineering plan in scale to it`s real measurements. (e.g., “10m x 15m”).
  • Floor Plan Name: Provide a name (e.g., “South-West Wing”).
  • Example: Floor plan “South-West Wing” with dimensions “10m x 15m” and image “south_west_wing.png”.

• Beacons (required only for indoor tracking):

  • Beacons can be either TEKTELIC or 3rd party.

  • For TEKTELIC Beacons:

    • Provide either the T-code, Serial Number, Revision, or DevEUI (e.g., DevEUI: “647FDA000001F136” or T-code “T0007127”/Revision “A1”/Serial Number “2020A0101”).
    • Specify the localization mode (e.g., “Regular” or “Nearest”).
    • Optional: TEKTELIC beacons can be onboarded on the Network Server for beacon`s battery life, RSSI, SNR, PSR information.

  • For 3rd Party Beacons:

    • Required fields: Name (e.g., “Beacon1”), MAC Address (e.g., “AC:23:3F:01:82:02”), and localization mode (e.g., “Regular”).
    • Beacon Model: Specify the model (e.g., “beacon_model”). Contact TEKTELIC support engineer to create a beacon model.
    • Example: Beacon “Beacon1” with MAC “AC:23:3F:01:82:02” in “Regular” mode, using model “beacon_model”.

Download and fill out the following CSV template:

Asset Name;Asset Type;Home Site;Device EUI;Tags;Description
My asset;My asset type (optional);My site;647FDA00000XXXXX (optional);My tags (optional);My description (optional)

• Asset Name (Required): A unique name for the asset (e.g., “Carriage 20B”).
• Home Site (Required): The site where the asset is primarily located (e.g., “Madrid”).
• Asset Type (Optional): The type of asset, which can be predefined (e.g., “Pelican” or “Chickadee beacon_model”).
• Device EUI (Optional): The EUI of the device bound to the asset (e.g., “647FDA000001F136”).

Overview

The specific geofence(s) on either the indoor or outdoor map where the asset was located at the time the device generated the report

• Draw any geofences to be created on the floor plan or outdoor map, if necessary.
• Provide an example of the needed geofence (e.g., “Room 9 Geofence” on floor plan “South-West Wing”, covering a 5m x 3m area in the conference room).

• List any event rules to be bound with geofences, if necessary. Please use any tool any tool at their discretion

• Possible trigger options:

  • Enters Geofence: Triggers when an asset enters a specified geofence.
  • Exits Geofence: Triggers when an asset exits a specified geofence.

• Example: Event rule “indoor 2 enter” for geofence “Room 9 Geofence” to trigger on asset entry; event rule “low battery alert” to trigger on device low battery.

Provide a list of users in the following CSV template:

Name,Email,Write Only Permission,Read Only Permission,Location Based Permission
"John Doe","johndoe@tektelic.com","true","false","Madrid"
"Jane Smith","janesmith@tektelic.com","false","true",""

• Name (Required): The full name of the user (e.g., “John Doe”).
• Write Only Permission (Required): Set to “true” if the user can write and read data, “false” otherwise.
• Read Only Permission (Required): Set to “true” if the user can only read data, “false” otherwise.
• Location Based Permission (Optional): Specifies the site(s) the user can access (e.g., “Madrid”). If empty, the user has access to all sites.

Location-based permission restricts a user’s access to specific sites within the Locus application. For example, a user with location-based permission set to “Madrid” can only view or manage assets, geofences, and events associated with the “Madrid” site. This ensures that users only interact with data relevant to their assigned locations, enhancing security and operational efficiency.

This section applies only to STORK and CHICKADEE devices.

• A Semtech Key can be used to use GNSS features of STORK and CHICKADEE devices with the Locus application.
• Users may provide their own Semtech Key for integration.

• Provide the following details to the support engineer:

  • Which LoRaWan Network Server will be used in the solution.
  • The Semtech Key you wish to use.

• To integrate your Semtech Key with Locus, contact a support engineer.