Location Alias API
Automating Device Location Updates on Big Block
The Location Alias feature allows a single physical device to represent multiple logical “sub-locations.” Imagine you have a cart with four slots; rather than attach a separate device to each slot, you can place one device on the cart, then create four Location Aliases—one for each slot. Each alias can display its own custom content, direction arrow, or barcode when you send commands referencing it.
By separating physical hardware (the “device”) from the logical locations (the “aliases”), you can easily:
- Provide directional cues (e.g., “Above and to the left”) right on the e-ink display.
- Send targeted commands to one shelf (alias) without affecting the others.
- Update or remove aliases without physically touching the device.
This is particularly useful for large environments with multiple shelves or sections where you want a minimal number of physical devices but maximum flexibility in showing distinct instructions, barcodes, or directions.
Example Overview
Below is a condensed example showing how to:
- Clear old aliases on a given device, in case it was previously assigned to other locations.
- Add new aliases to represent each sub-location.
- Issue a command to a specific alias (showing how the server automatically knows which direction arrow to draw, if any).
import requests
import json
session = requests.Session()
baseurl = "https://www.voodoodevices.com/api/"
# Assume 'headers' has been set up to include your auth token or API key
location_alias_url = f"{baseurl}location-aliases/"
def clear_locations_around_device(deviceid):
"""Remove any existing location aliases for a particular device."""
response = session.get(location_alias_url, headers=headers)
if response.status_code == 200:
for location in response.json():
if location['deviceid'] == deviceid:
delete_url = f"{location_alias_url}{location['id']}/"
session.delete(delete_url, headers=headers)
def add_location_alias_for_device(deviceid, alias_name, device_is):
"""Create a new location alias for a device."""
session.post(
location_alias_url,
json={'name': alias_name, 'deviceid': deviceid, 'deviceIs': device_is},
headers=headers
)
# Example usage:
device_id = "ABC123:DEF456"
# 1) Clear any old aliases
clear_locations_around_device(device_id)
# 2) Add aliases for “Left Shelf” and “Right Shelf”
add_location_alias_for_device(device_id, "CartA-Left", "to the Left of")
add_location_alias_for_device(device_id, "CartA-Right", "to the Right of")
# 3) Now, you can send commands with "location" referencing "CartA-Left" or "CartA-Right"
# instead of a device ID.
# The server knows which device to choose and which arrow/direction to show based on the alias definition.
devices_url = f"{baseurl}devices/"
session.post(
devices_url,
json={'location': 'CartA-Left', 'command': 'flash', 'line1': 'Hello', 'barcode': 'abc123'},
headers=headers
)
With these steps, you’ve turned a single physical device into two separately identifiable “locations.” You can create as many aliases as you need (e.g., “Top Shelf,” “Bottom Shelf,” “Bin A,” “Bin B,” etc.), each with its own directional arrow or descriptive text.
In the sections below, we’ll define the Location Alias API more formally, including endpoints, parameters, and important status codes to watch for.
API Description
Conclusion
These endpoints let you list, create, retrieve, and remove Location Aliases. By providing an easy mapping from a single hardware device to multiple named/directional sub-locations, your application can handle more flexible layouts without deploying extra devices. Once aliases are created, you can target them by name when sending commands (e.g., “flash” or “display”), and the server automatically knows which device to choose, and which arrow or directional label to render.