Utilizing Location Raw Update Events in Python

Set up and utilize Location Raw Update events using Python.

This type of event is defined as a position update from a ZeroKey Mobile containing the last known X, Y, and Z coordinates in meters and the orientation as a quarternion.

Getting Started

To integrate Location_Raw_Update event listening into your Python script and handle the incoming data, follow these steps:

Before diving in, ensure you have the necessary tools:

1. Python 3.X version

2. requests library

3. signalrcore library

You can install the required libraries using the pip function.

pip install requests signalrcore

Once installed, you’re set to start listening for Location_Raw_Update events and processing data in Python.

Our API page contains more information on how Location Raw Update works and how you can interpret its output in the log.

The following link will direct you to this page: https://api.zerokey.com/v3/#section/Event-Hub/Event-Schema

• Scroll down to Event Categories and click on the Content dropdown menu under LOCATION_RAW_UPDATE to see the definitions of each object in the output.

Imports and Definitions

Ensure you import the necessary modules, as shown below.

import requests
import json
from signalrcore.hub_connection_builder import HubConnectionBuilder

Ensure to also define URLs for the event hub and API. Start by navigating to these two lines of code:

eventHubUrl = http://{API Host Here}:33001/hubs/eventHub
apiUrl = http://{API Host Here}:5000/v3/

It’s important to note that the port values 33001 and 5000 are fixed, meaning they cannot be changed. Only the IP address placeholders, represented as {API Host Here}, should be replaced with the IP address of the Edge Compute Device (ECD).

After replacing the placeholders with the correct IP address, the lines will look like the following example, where the sample ID address used is 10.22.74.129.

eventHubUrl = http://10.22.74.129:33001/hubs/eventHub
apiUrl = http://10.22.74.129:5000/v3/

The Handle Location Raw Update Function

This function is triggered when an event named Event is received from the hub. It it represented in the code as the handle_location_raw_update function, as shown below.

def handle_location_raw_update(data):
json_str = data[0]
event_data = json.loads(json_str)
if event_data['Type'] == 'LOCATION_RAW_UPDATE':
print(f"Received LOCATION_RAW_UPDATE:(event_data)")

This function parses the event data and checks if the event type is LOCATION_RAW_UPDATE. If it is, the event data is printed in the output.

The Main Function

This function sets up the SignalR hub connection and event listeners. It is represented in the code as the main() function, as shown below.

def main():
.hub connection = HubConnectionBuilder() \
.with url (eventHubUrl, options={"access token factory":
authenticateConnection, "logging": "debug"}) \
.build()

hub_connection.on open(lambda: print("Connection opened and handshake received; ready to send messages"))
hub_connection.on close(lambda: print("Connection closed"))
hub.connection.on("Event", handle_location_raw_update)
hub_connection.start()
while(True):
pass

Refer to our help article Connecting to ZeroKey’s API with Python for more guidance.

Running the Script

Start Python, then execute the script using the following command in the terminal or command prompt:

python name_of_your_script.py

Note: Ensure to navigate to the directory where the script is saved.

The following is an example of what this may look like in the output:

C:\Users\admin\pycharmProjects\API 4\API\API>python TestingZKAPI.py

The name of the script in the example used above is TestingZKAPI.

After successfully running the script, you should see the following in the first line of the output:

Connection opened and handshake received; ready to send messages

The remainder of the output provides information on positioning, timestamp, rotation, MAC address, ultrasonic flags, and INS flags.

Interpreting the Output

The following is an example of the script’s output:

Received LOCATION_RAW_UPDATE: {'Category': 'POSITION', 'Type': 'LOCATION_RAW_UPDATE', 'Timestamp': '2024-05-06T19:16:00.6992Z', 'Content': {'MAC': 'F0:CC:E4:33:71:E2', 'Sequence': 3364, 'RelativeTimestamp': 1715022960, 'Position': [-0.6935382868365352, -1.2107847125853122, -0.004787646895766497], 'Orientation': [0.0, 0.0, 0.0, 0.0]. 'Velocity': [-0.0006570757116781472, 8.887650013922406e-05, 8.98924906475392e-05], 'Flag': 2, 'InsState': 3, 'UsState': 3, 'TransitTime': 63850619760648024}, 'Source': {'MAC': 'F0:CC:E4:33:71:E2', 'SiteID': 1, 'GatewayURI': ''}, 'LocalTimestamp': '2024-05-06T19:16:00.6992Z'}

The following table provides definitions for the relevant terms in the script’s output:

A user can benefit from this script in different ways:

• Track and Monitor Location in Real Time: Monitor position, orientation, and flags for logistics or operational efficiency.

• Analyze Timing and Duration of Events: Optimize processes using timestamps and event sequences.

• Understand Device and System Status: Ensure high solve quality by reviewing INS and US states.