Skip to content

Quickstart

Five minutes from zero to a working script.

1. Set environment variables

export RTLS_USERNAME="qa@example.com"
export RTLS_PASSWORD="hunter2"
export RTLS_BASE_URL="https://rtls.example.com"
# optional default scope
export RTLS_PROJECT_UID="proj-abc"

2. Run

from rtls_sdk import RtlsClient

with RtlsClient.from_env() as client:
    tags = client.tags.list()
    for tag in tags:
        print(tag.uid, tag.name)

Output:

t-1 Forklift 7
t-2 Forklift 8

That's it. The first method call (client.tags.list()) triggered a silent login. Token, refresh, scoping headers, 401 re-login — all internal.

3. The two patterns

Read everything for the dashboard

ctx = client.context.load()
print(f"{len(ctx.tags)} tags, {len(ctx.sites)} sites, {len(ctx.users)} users")

context.load() fans out the dashboard's bootstrap fetches in one call. Use this when you need a snapshot.

Compound workflow — create a tag, attach to a zone, add to groups

tag = client.tags.create(
    name="Forklift 9",
    attached_zone={"shape": "circle", "geometry": {"radius": 3000}},
    groups=["g-fleet", "g-priority"],
)
print(tag.uid)

One method, one return value. Behind the scenes the SDK creates the tag, the bound zone, and the group memberships — rolling back on partial failure.

Tags don't carry a MAC address — that belongs to a separate Node. To bind hardware to a tag you also call client.nodes.create("aabbccddeeff") and client.tag_associations.create("aabbccddeeff", tag.uid). A compound wrapping the three calls is planned for a future milestone.

Live updates

from rtls_sdk import PositionMessage

with client.ws.subscribe(["pos"]) as session:
    for msg in session:
        if isinstance(msg, PositionMessage):
            print(msg.mac, msg.x, msg.y)
            break

See Streaming for channels, reconnects, and REST → WS round-trips.

What next