Subscriber Guide¶
A five-minute path to receiving your first Dory event. This is the quickstart; the full reference lives in the Application SDK section. One thing to know before you start: subscribing is asynchronous. Dory accepts your request at once, sets the subscription up in the background, and the SDK tells you when it is ready.
The big picture¶
Dory streams events from cameras and sensors (things like moving, person, accidents). As a subscriber you tell Dory three things:
- What you care about — a list of event types.
- Where — a list of regions: geohash cells of 1 to 9 characters (short codes for areas on a map), or
*alone for everywhere you can see. A region selects the sensors whose area of view touches it — not the pin on the map — and every event those sensors' processors publish for your event types is delivered. - How the raw data should be processed — a lens, a named group of processor templates. Use one your organization created, or a public one shared by another organization.
Dory delivers matching events to your app in real time, as plain Python dictionaries handed to a callback. You don't manage queues or connections — the SDK does, and your callback only ever sees events. For the concepts, see Core Concepts.
The lifecycle at a glance¶
Everything that happens after Dory accepts your request — readiness or failure, events, later changes in coverage — arrives in your own delivery queue. The SDK separates the status messages from the events for you.
sequenceDiagram
autonumber
participant App as Your app (SDK)
participant API as Dory API
participant Q as Your delivery queue
participant W as Dory (provisioning)
participant P as Processors
App->>API: subscribe(event types, regions, lens)
API->>Q: create the queue
API-->>App: accepted (202) — subscription id, status pending
Note over App,Q: The SDK starts listening on the queue immediately
App->>App: wait_until_ready(subscription_id)
W->>W: match sensors by area of view, choose templates from the lens
W->>P: start a processor per sensor and template (or reuse a running one)
W->>Q: route each processor's events to the queue
alt set up
W->>Q: control message: ready + coverage report
Q-->>App: wait_until_ready returns the coverage report
else setup failed
W->>Q: control message: error + code
Q-->>App: wait_until_ready raises SubscriptionError
end
Note over App,Q: Control messages are handled by the SDK and never reach your callback
P->>Q: events (may begin before ready)
Q-->>App: callback(event)
loop every hour
W->>W: re-check the match
W->>Q: control message: updated (only when coverage changed)
end
App->>API: unsubscribe(subscription_id)
API->>Q: delete the queue — delivery stops now
API-->>App: accepted (202) — status deleting
W->>P: release processors no other subscription uses
Prerequisites¶
- Python 3.10+
- An app client (client ID + secret) — create one in the Portal. The SDK asks for the scopes to read platform metadata, read from the message broker, and read, create and delete its own subscriptions, so the client needs those.
- A lens you can use — one your organization created in the Portal, or a public one — and its alias.
Quickstart¶
# 1. Install (from a clone of the backend repo — the SDK is not on PyPI)
cd sdk/python && pip install -e .
# 2. Set your credentials
export DORY_CLIENT_ID="your client id"
export DORY_CLIENT_SECRET="your client secret"
# 3. Subscribe, wait until it is ready, receive events
import time
from dory import DoryClient
def handle_event(event: dict):
print(f"Event received: {event}")
client = DoryClient() # reads DORY_CLIENT_ID / DORY_CLIENT_SECRET
subscription_id = client.rabbitmq.subscribe(
event_types=["moving", "person"], # what
geohash_regions=["dhxpfr5"], # where
lens_alias="demo-lens", # how (your lens, or a public one)
callback=handle_event,
) # accepted at once; Dory sets it up in the background
print(f"Subscription accepted: {subscription_id}")
coverage = client.rabbitmq.wait_until_ready(subscription_id, timeout=120)
print(coverage["event_types"]) # blocks until ready; returns what was matched
try:
while True:
time.sleep(1) # events arrive on a background thread
except KeyboardInterrupt:
pass
finally:
client.rabbitmq.unsubscribe(subscription_id) # stops delivery immediately
client.close() # unsubscribes anything else this process created
What just happened
subscribe()sent the request. Dory accepted it (statuspending), created your delivery queue, and the SDK started listening on it at once.- In the background, Dory matched sensors by area of view, chose templates from the lens, started — or reused — one processor per sensor and template, and wired their events to your queue. Processors are shared: if another subscription already runs the same template on the same sensor, yours reuses it.
- The
readycontrol message carried the coverage report, andwait_until_readyreturned it. Events may already have arrived while you waited. unsubscribe()stops delivery immediately; the processors behind the subscription are released shortly after.
Delivery
Events are delivered at least once — key your handler on the message's message_id. Control messages (ready, updated, error) are handled by the SDK and never reach your callback. See Consuming Events.
Run it. The subscribe call returns as soon as Dory has accepted the request; wait_until_ready blocks until Dory has finished setting the subscription up and returns a coverage report saying, per event type, whether anything in your region can produce it. Then generate some activity in your region and watch events print.
Skip the code
The App Request Builder in the portal lets you pick event types, click geohash cells on a map and choose a lens, then generates the subscribe call for you.
Reading the coverage report¶
The report wait_until_ready returns has two parts. event_types maps each event type you asked for to covered: true or covered: false — and, when false, a reason. After that come four counts: sensors_matched (sensors whose area of view touches your regions), sensors_served (those Dory assigned at least one processor to), processors_started and processors_reused. The report names no sensors or processors; it only counts them.
| Reason | What it means | What to do |
|---|---|---|
NO_SENSORS_IN_REGION |
No sensor you can see has an area of view touching your regions. | Check the portal's sensor map, or widen the region. |
NO_TEMPLATE_EMITS_IT |
No template in the lens with an approved version produces this event type. | Attach one to the lens, or ask the template's owner. |
NO_COMPATIBLE_SENSOR |
A template in the lens produces it, but none of the matched sensors is a type that template accepts. | Widen the region, or attach a template that accepts those sensor types. |
LENS_NOT_ACCESSIBLE |
The lens was deleted, or another organization made its lens private, after you subscribed. | If the lens is made public again, coverage comes back on its own. A deleted lens does not come back: delete the subscription and subscribe with another lens. |
Dory makes the four checks in this order for every event type you requested:
flowchart TD
A["Requested event type"] --> B{"Is the lens still yours, or public?"}
B -- no --> R1["covered: false — LENS_NOT_ACCESSIBLE"]
B -- yes --> C{"Does any sensor you can see have an area of view touching your regions?"}
C -- no --> R2["covered: false — NO_SENSORS_IN_REGION"]
C -- yes --> D{"Does a template in the lens with an approved version produce this type?"}
D -- no --> R3["covered: false — NO_TEMPLATE_EMITS_IT"]
D -- yes --> E{"Does that template accept one of the matched sensors' types?"}
E -- no --> R4["covered: false — NO_COMPATIBLE_SENSOR"]
E -- yes --> OK["covered: true"]
Nothing matched is not an error
A region with nothing in it is still a live subscription: its status is active and its coverage report says, per event type, why nothing is covered yet. Dory re-checks every active subscription every hour — a sensor installed, published, moved or decommissioned, a template attached to the lens or removed from it, a lens made private, deleted or made public again — and sends an updated control message whenever your coverage changes, which the SDK logs. Leave the app running; do not resubscribe.
client.get_subscription(subscription_id) returns the same report once the subscription is set up, together with the subscription's status.
When something goes wrong¶
A subscription's status as you see it:
stateDiagram-v2
[*] --> pending: subscribe() accepted
pending --> active: ready control message (coverage report — possibly empty)
pending --> error: setup failed → error control message with a code
active --> active: hourly re-check → updated message if coverage changed
pending --> deleting: unsubscribe()
active --> deleting: unsubscribe()
error --> deleting: unsubscribe() — then subscribe again
deleting --> [*]: queue removed at once, processors released shortly after
Refused before it starts¶
When Dory refuses a subscription, subscribe() raises one error class per reason. All of them are RuntimeErrors, importable from dory (from dory import TooManySensors), and all share the base class SubscriptionRefused if you would rather catch them together. Each carries .code (the reason, such as TOO_MANY_SENSORS) and .status (the HTTP status).
| Error | Why | What to do |
|---|---|---|
UnknownEventType |
An event type the platform does not know. The SDK also checks the list before sending anything and raises ValueError for a typo. |
Pick from client.get_metadata(), which lists the platform's event types. |
LensNotAccessible |
No lens by that alias you can use — unknown, or private to another organization. | Check the alias in the portal. |
InvalidRegion |
A malformed geohash, or * mixed with cells. |
Send valid cells, or * on its own. |
RegionTooFine |
A cell longer than 9 characters. | Use cells of 9 characters or fewer. |
TooManyCells |
More than 64 distinct cells, after nested ones collapse into the coarser cell that contains them. | Use fewer, coarser cells. |
TooManySensors |
More than 200 sensors would match. | Ask for a smaller area. |
QuotaExceeded |
Your organization already holds 100 subscriptions that have not been deleted — pending and error ones count too. |
Delete one first. |
BrokerUnavailable |
Dory could not create your delivery queue. Normally nothing is left behind; if the queue could not be cleaned up either, the attempt stays in your list with status error and code QUEUE_ORPHANED. |
Retry. Delete any leftover error subscription. |
It failed after being accepted¶
wait_until_ready raises SubscriptionError when the status becomes error. The error's .code says why and its .message is a plain sentence saying what to do; the portal explains the same code in the app client's details. Dory does not retry a subscription in error, and it keeps counting toward your organization's limit until you delete it.
| Code | What happened | What to do |
|---|---|---|
BROKER_REFUSED |
The message broker refused a request while Dory was setting the subscription up. Trying the same setup again cannot fix it. | Delete it and subscribe again. If it keeps failing, contact support with the subscription ID. |
PROVISIONING_FAILED |
Dory tried to set it up five times and hit temporary failures every time. | Delete it and subscribe again. If it keeps failing, contact support with the subscription ID. |
QUEUE_ORPHANED |
Dory could neither create your delivery queue nor clean it up; your subscribe() call raised BrokerUnavailable at the time. |
Delete it — that also removes whatever was left of the queue — and subscribe again. |
LEGACY_RESUBSCRIBE |
The subscription was created before the current delivery system (September 2026). | Delete it and subscribe again. |
Still pending¶
wait_until_ready raises SubscriptionTimeout (a TimeoutError) when Dory had not finished within the timeout and, asked directly, confirmed the subscription is still pending. Dory keeps working on it in the background: call wait_until_ready again, or read client.get_subscription(subscription_id).
Checking on it later. client.get_subscription(subscription_id) returns the status, the coverage report and, for a subscription in error, its lastErrorCode; client.list_subscriptions() returns every subscription of this credential that has not been deleted — pending, active and error alike, each with its lastErrorCode. See Managing Subscriptions.
Unsubscribing¶
client.rabbitmq.unsubscribe(subscription_id) is accepted at once. Delivery stops immediately, because your delivery queue is removed inside the request; the processors no other subscription uses are released shortly after, in the background.
A subscription outlives your process until you delete it, so always unsubscribe — or call client.close(), which unsubscribes every subscription this process created. Deleting a subscription that is already gone is a no-op. A credential can delete only its own subscriptions: trying to delete one that belongs to another app client in your organization raises an error and leaves the subscription in place. A subscription can also be deleted from the portal, in the app client's details.
Next steps¶
- Application SDK: Getting Started — install, concepts, and a guided first run.
- Managing Subscriptions — list, name, and delete subscriptions.
- Consuming Events — the callback and delivery model.
- Configuration — custom API URLs and Cognito domain.
- API Reference — every class and method.
- API: Subscriptions — the HTTP contract, if you are not using Python.