Location Alias API

Managing device locations in Big Block — from simple 1:1 mappings to multi-location setups with automatic directional arrows.

Location Management Options

When using Big Block, you have several options for how to handle "location" information for your devices. This is completely optional — if you already have your own way of matching devices to their physical locations, feel free to continue using that approach.

Option 1: Maintain Location Information Yourself

You can skip storing any location data in Big Block entirely:

Each device is known to Big Block only by its unique DeviceID
You track which physical spot in your facility the device belongs to
All API calls are made directly to DeviceIDs — no location concept is used within Big Block

Option 2A: Simple `locationoverride`

Every device has a locationoverride field you can set via the Device API or the Big Block GUI. This is a static setting (persistent background state), not a command parameter.

Ideal for 1:1 setups: one device permanently tied to one location
The location name will appear on the device's display when specified
Only supports one location per device
No automatic arrow display (unless you manually send an arrow command)

Limitation

Because locationoverride is just one field, it only supports one location per device. There's no automatic arrow or multi-location setup built in.

Option 2B: Location Aliases — Multi-Location with Automatic Arrows

For advanced scenarios — like a single device representing multiple sub-locations (e.g., multiple shelves on a single cart):

A single device can have multiple aliases, each representing a different spot (top shelf, bottom shelf, left bin, right bin, etc.)
Automatic arrows: when you send a command to a particular alias, Big Block knows which arrow to display based on that alias's deviceIs configuration
You can update or remove aliases without physically touching the device

Approach Comparison

Approach	Best For	Automatic Arrows
No Big Block location data	You have your own location tracking system	No
locationoverride	1:1 device-to-location mapping	No
Location Aliases	Multi-location per device, cart scenarios	Yes

Tip

The API approach is more scalable: you can script bulk changes if your layout changes frequently, and you can programmatically assign different location labels or directions to a single device.

Location Alias API — Overview

The Location Alias feature allows a single physical device to represent multiple logical "sub-locations." Imagine 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 per 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:

Provide directional cues (e.g., "Above and to the Left of") 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

Tip

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.

Endpoint Reference

Base URL: https://www.voodoodevices.com/api/

Method	Endpoint	Description
GET	`/location-aliases/`	List all location aliases
POST	`/location-aliases/`	Create a new location alias
GET	`/location-aliases/{id}/`	Retrieve a specific alias
DELETE	`/location-aliases/{id}/`	Delete a location alias

Request Body (POST)

Parameter	Type	Description
`name`	string	Friendly name for the alias (e.g., "CartA-Left")
`deviceid`	string	The DeviceID of the physical device
`deviceIs`	string	Directional relationship — where the physical device is relative to this alias location (e.g., "to the Left of", "Above")

OpenAPI Specification

OAS 3.0

This API is fully OpenAPI Specification (OAS 3.0) compliant. The machine-readable spec unlocks powerful integrations:

Postman: use Import → Link and paste the spec URL — all endpoints, parameters, and example bodies load automatically.
AI coding tools (GitHub Copilot, Cursor, ChatGPT, etc.): paste the spec URL and they generate accurate, working client code with correct field names and auth headers.
SDK generators: produce typed clients in any language with tools like openapi-generator or fern.

Spec URL:

https://bblock-demo.voodoorobotics.com/location-aliases/openapi.json

deviceIs Direction Values

The deviceIs field defines where the physical device is relative to the alias location. Big Block uses this to automatically draw the correct directional arrow on the display:

Above and to the Left of

Above

Above and to the Right of

to the Left of

to the Right of

Below and to the Left of

Below

Below and to the Right of

Naming Conventions

Use descriptive names that reflect the physical or logical layout:

CartA-Left, CartA-Right — carts with left/right positions
Rack3-TopShelf, Rack3-BottomShelf — racks with vertical positions
BinA, BinB — simple bin identification

Note

Once aliases are created, target them by name when sending commands — the server automatically selects the correct device and renders the appropriate arrow or directional label.

Complete Example

This example clears old aliases for a device, creates new ones, then sends a command targeting an alias by name:

import requests
import json

session = requests.Session()
baseurl = "https://www.voodoodevices.com/api/"
location_alias_url = f"{baseurl}location-aliases/"

# Assume 'headers' has been set up with your auth token or API key
headers = {'API-KEY': 'your_api_key_here', 'Content-Type': 'application/json'}

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) Send a command using the alias name instead of DeviceID
devices_url = f"{baseurl}devices/"
session.post(
    devices_url,
    json={'location': 'CartA-Left', 'command': 'flash', 'line1': 'Hello', 'barcode': 'abc123'},
    headers=headers
)

REST API Overview

Core device endpoints and examples

Orders API

Order management and fulfillment tracking

Devices & Networking

Turbo placement and network setup

Best Practices

Arrows, display conventions, and deployment tips