Concepts

Gateways, endpoints, fields, readings, and what sure and unsure mean.

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 as loading_bay
  • a title people read, such as Bay 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.

typeIts valueFor example
choiceOne of 2 to 12 answers you nameopen, shut
yes_notrue or falseIs the bay free?
levelOne of 2 to 7 levels, lowest firstempty, half, full
colourOne of 2 to 12 states, told apart by colourred, green
numberA number. shows says whether it’s digits on a display or a dial’s needle72 with unit psi
textWords or a code, up to 200 charactersABC-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.

qualityMeansvalue
validSureThe value
uncertainUnsure. doubt says whyIts best reading, not to be relied on
noneNo reading. missing says whynull

Only sure values change anything. Webhooks and alerts act only on sure readings.

Find why a value is unsure

doubtMeans
readingThe reading itself wasn’t sure
target_movedThe thing may have moved
target_at_edgeThe thing sits at the edge of the frame
target_unlocatedThe thing wasn’t found, so a saved spot was read
camera_movedThe camera is out of place, so the spot read may be wrong
unseenA state this field was never seen in, unsure until Dialect agrees

Find why a value is missing

missingMeans
never_readNo reading yet
read_failedThe read failed
no_answer_fitsNone of the field’s answers fit
not_in_viewThe thing isn’t in view
coveredSomething is in front of it, with the camera in place
nothing_shownA 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.stateMeans
okIt’s in place
movedThe fixed objects it checks are elsewhere in view
lostA check couldn’t find one of them
uncheckedNo check has said yet, or the last couldn’t run
not_watchedNo 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.

Next steps