Learn the words the rest of these docs use. At the end you’ll know what a reading says and when to trust it.
See what a gateway does
A gateway is the program beside your camera. It watches the camera, reads what it’s asked to, and reports to Dialect. Each gateway has one camera and an ID such as loading-dock. See Connect a camera.
One camera can answer many questions. Each question is its own endpoint on the same gateway.
See what an endpoint holds
An endpoint is one question Dialect keeps answering for you. It has:
- a
name, the stable identifier your code uses, such asloading_bay - a
titlepeople read, such asBay free - a
purpose, one sentence on what it’s for - one or more fields, the typed values it returns
every_s, how often it checks: 5 seconds unless set otherwise, from 2 to 3,600
Most tools and routes also find an endpoint by its title, so loading_bay, Bay free and bay free all name the same one.
An endpoint has versions. Changing what it reads makes a new version that a person confirms, while the name stays the same.
Choose a field kind
A field is one value. Its type says what it can hold.
type | Its value | For example |
|---|---|---|
choice | One of 2 to 12 answers you name | open, shut |
yes_no | true or false | Is the bay free? |
level | One of 2 to 7 levels, lowest first | empty, half, full |
colour | One of 2 to 12 states, told apart by colour | red, green |
number | A number. shows says whether it’s digits on a display or a dial’s needle | 72 with unit psi |
text | Words or a code, up to 200 characters | ABC-123 |
A choice, yes/no or colour field can also tell a flashing light from a steady one. See Build one by hand.
Follow a reading
A reading is one time a model looks at a photo. Checks that find the photo unchanged don’t count. Dialect keeps a field’s current value, and in its history keeps each change and each unsure reading. It reads again when the picture changes, and at least every 10 minutes when it doesn’t.
Tell sure from unsure
Every value has a quality.
quality | Means | value |
|---|---|---|
valid | Sure | The value |
uncertain | Unsure. doubt says why | Its best reading, not to be relied on |
none | No reading. missing says why | null |
Only sure values change anything. Webhooks and alerts act only on sure readings.
Find why a value is unsure
doubt | Means |
|---|---|
reading | The reading itself wasn’t sure |
target_moved | The thing may have moved |
target_at_edge | The thing sits at the edge of the frame |
target_unlocated | The thing wasn’t found, so a saved spot was read |
camera_moved | The camera is out of place, so the spot read may be wrong |
unseen | A state this field was never seen in, unsure until Dialect agrees |
Find why a value is missing
missing | Means |
|---|---|
never_read | No reading yet |
read_failed | The read failed |
no_answer_fits | None of the field’s answers fit |
not_in_view | The thing isn’t in view |
covered | Something is in front of it, with the camera in place |
nothing_shown | A display or label shows nothing to read: blank, off or dashes |
Check that a value is fresh
fresh says whether a value is current. It’s false when the gateway is offline, a read failed, the endpoint is paused, or the field hasn’t been confirmed lately: within three checks, and at least 90 seconds. A sure value that isn’t fresh is an old answer. See Handle unsure values.
Check that the camera is in place
Each endpoint also reports whether its camera is where it was tested.
camera.state | Means |
|---|---|
ok | It’s in place |
moved | The fixed objects it checks are elsewhere in view |
lost | A check couldn’t find one of them |
unchecked | No check has said yet, or the last couldn’t run |
not_watched | No field names a fixed object to check against |
camera.effect says what that does to this endpoint: none, readings_stand when every value was read where its target is now, or out_of_place when some value suffers.
Confirm a proposal
A proposal is a version waiting for a person. It shows the photo and what each field reads now. A workspace administrator confirms it, and only then does it run. See Confirm an endpoint.
Control who reaches what
A workspace holds your gateways, endpoints and people. Access is per gateway: a token or person reads only the gateways they were granted. See Authenticate a request.
A question is one endpoint. It can answer with several fields. See billing.