Access service #

Service namespace: access

Responsible for giving access to identities from NFC or BLE and controlling lock and display.

Configuration #

Config json schema available on api/v1/device/<dev_id>/service/access/config/schema:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/<dev_id>/service/access/config/schema

Read config with status:

curl -H "X-IOTREADY-CONFIG-NEXT-GEN: true" -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/<dev_id>/service/access/config

Configure open access:

curl -H "X-API-Key: <api key>" -X PUT \
    -d '{"enable":true,"open_access":true}' \
    https://api.nr.iotready.no/api/v1/device/<dev_id>/service/access/config/value

Open counter #

With counter.limit set, the device counts successful opens and refuses access once limit have been counted, until the count is reset. It suits a container that has to be emptied after a number of uses.

• What counts is the lid actually opening after an open request the access service granted. An unlock nobody opened, or an unauthorized open, is not counted.
• At the limit every open request is refused, NFC and Bluetooth alike. The display shows the out-of-service text, and an access_declined event is sent if decline_notify is set.
• Tapping a reset card - one of counter.reset_uids - sets the count to 0 and opens the bin, for whoever empties it. That open is not counted, so the count stays at 0 until the next customer. The display shows the operator logo, then the usual screens as it opens. The card resets the count whatever enable says, but opens only while access is enabled, and it does not have to be on the NFC access list.
• The reset_counter command sets the count, 0 by default, and opens nothing.
• The count survives reboots, and is not part of the configuration: setting the config never changes it, and lowering the limit below it refuses access at once.
• While a limit is set, opened, access_declined and counter_reset events carry counter.count and counter.limit. The opens left are limit - count, or none once the count has reached the limit. The count is what the resets leave it at, so it says nothing about use: to count use, count the opened events, since the last counter_reset for opens since an emptying.

Enable a limit of 40 opens, with a reset card:

curl -H "X-API-Key: <api key>" -X PATCH \
    -H "Content-Type: application/merge-patch+json" \
    -d '{"counter":{"limit":40,"reset_uids":["04A1B2C3D4E5F6"]}}' \
    https://api.nr.iotready.no/api/v1/device/<dev_id>/service/access/config/value

Commands #

unlock #

Grants access, as an accepted open request: the lock unlocks and the access service handles the opening as it does for a valid NFC tag. Only over Bluetooth, while the device is attached to the live tunnel.

curl -H "X-API-Key: <api key>" -X POST -d '{"uuid":"door-7"}' \
    https://api.nr.iotready.no/api/v1/device/<dev_id>/service/access/live/cmd/unlock

uuid is optional and is recorded as the open request’s origin.ble.id: 1 to 16 characters, or a UUID, which is sent as its 16 bytes. Leave the body as {} for no id.

The response is the device’s answer, an access event: unlocked when the lock opens, access_declined when the open counter’s limit is reached (only with decline_notify set), lock_not_configured without a lock, or lock_error. No answer comes back, and the request times out, when the lock is still unlocked from the previous grant (the device ignores the new one), or when the counter refuses without decline_notify.

reset_counter #

Sets the open counter’s count; count defaults to 0.

Through the cloud, queued and delivered on the device’s next exchange:

curl -H "X-API-Key: <api key>" -X POST -d '{"count":0}' \
    https://api.nr.iotready.no/api/v1/device/<dev_id>/service/access/cmd/reset_counter

The response is {"queued": "<id>", "count": 0}. The device confirms with a counter_reset event.

Over Bluetooth, while the device is attached to the live tunnel, the same command is answered at once with the device’s counter_reset event:

curl -H "X-API-Key: <api key>" -X POST -d '{"count":0}' \
    https://api.nr.iotready.no/api/v1/device/<dev_id>/service/access/live/cmd/reset_counter

Messages #

Event #

Message name: event

Events have the following structure. opened, opened_timeout, closed_timeout, unauthorised_access, access_declined, lock_not_configured, lock_error, unlocked, closed and counter_reset are oneof type.

Read message:

curl -H "X-API-Key: <api key>" \
    https://api.nr.iotready.no/api/v1/device/<dev_id>/service/access/message/event

Errors #

For locks with error states these will be reported as lock_error events.