Device Types

Every piece of Bikeep IoT parking hardware that you can control via the API is a device. Devices are grouped into locations and identified by a UUID. This page describes each device type, what it does physically, and what commands it supports.

Overview

Note: The commands listed above are typical for each device type. In practice, available commands depend on the configuration of each specific device. Check the commands field in the device response for the authoritative list of commands a given device supports.

Administrative commands: Additional commands for operator/maintenance scenarios — force-lock, force-unlock, force-cancel-booking, and sync-device — are available via the API. These are not listed in the per-device tables above (which focus on user-facing flows). See the Device API Reference for details.

LOCKER

A locker is an individual enclosed storage compartment. Lockers can be either provided by Bikeep or just have the Bikeep IoT integrated into them. Physically, it is an enclosed compartment with an electronically controlled lock and an RFID reader.

Physical behavior

• The door has a sensor that detects open/closed state
• The lock is electronically controlled — it cannot be opened without an API command or an authorized RFID card
• The RFID reader accepts cards that are on the device’s whitelist

Available commands

See Sessions for the full session lifecycle.

RFID interaction

• Whitelist tap on unlocked device: locks the device, activating a session tied to that RFID card
• Whitelist tap on locked device (same card): unlocks the device, ending the session
• Master key tap on locked device: unlocks regardless of which card locked it

Monitoring

GET /device/v1/devices/{device_id}

Key response fields:

• state.value — current device state (UNLOCKED, LOCKED, BOOKED, etc.)
• state.changed_at — when the state last changed
• state.timeout_at — when the current state expires. Meaning depends on the state: BOOKED → booking ends, ALLOCATED → command has timed out, LOCKING → device will disengage, UNLOCKING → device has moved to unlocked. null when no timeout applies
• hardware_state — physical hardware health. In practice, only NORMAL and NOT_RESPONDING are used (with NOT_RESPONDING being used for legacy G1 bike docks)
• heartbeat_health — deprecated, use heartbeat_v2.health instead. Values: HEALTHY, UNHEALTHY, DEAD (does not distinguish LONG_DEAD from DEAD)
• heartbeat_v2.health — HEALTHY, UNHEALTHY, DEAD, or LONG_DEAD
• heartbeat_v2.dead_since — when the device went offline (null if healthy)

For availability monitoring across all devices at a location, use the Location API rather than polling individual devices:

GET /location/v1/locations/{location_id}

The devices.available field returns the count of devices that are both available AND online — use this for availability display rather than computing it yourself.

See State Machines for the full state transition diagram.

GUARD (IoT Gateway)

A guard is an IoT gateway and parent controller. Every bike house (bike room, hangar, or dockless space) and standalone locker/dock location has one or more GUARD devices that bridge all child devices — BIKE_HOUSE_DOORs, LOCKERs, BIKE_DOCKs — to the Bikeep cloud via MQTT. The GUARD also stores and distributes allowlists (RFID access keys) to all its children.

Role in device hierarchy

A location can have multiple GUARD devices. The GUARD is the parent of every other device at its location. When you query devices at a BIKE_HOUSE location, the GUARD is the gateway and all other devices (BIKE_HOUSE_DOOR, LOCKER, BIKE_DOCK, etc.) are its children. At standalone locations (BIKE_LOCKERS, BIKE_DOCKS), the GUARD similarly serves as the gateway for all LOCKERs or BIKE_DOCKs. The GUARD itself is not user-facing — users interact with the BIKE_HOUSE_DOOR (to enter the bike room) and interior devices (LOCKERs or BIKE_DOCKs) to store items.

Allowlist distribution

Whitelists and their targets (which GUARDs or locations receive the keys) are configured by Bikeep during station provisioning. As an integrator, you manage the entities — adding and removing RFID cards on existing whitelists via the API. The GUARD then distributes these keys to all its child devices, including BIKE_HOUSE_DOORs and any interior devices (LOCKERs or BIKE_DOCKs). This model applies to both bike house locations and standalone locker/dock locations. You do not need to manage allowlists per-child-device — the GUARD handles distribution automatically.

See Locker & Dock Integration — Step 4 for the entity management workflow.

Available commands

The GUARD has no device-control commands (no lock, unlock, book, etc.). If the GUARD has a camera connected, the take-photo command is available to capture a snapshot. Door access is handled by the BIKE_HOUSE_DOOR device, not the GUARD.

Monitoring

The GUARD reports connectivity and heartbeat data, but its state values are not operationally meaningful in the way locker or dock states are. Monitor the GUARD’s heartbeat_v2.health to assess whether the gateway (and by extension, its children) is online. The legacy heartbeat_health field is deprecated — it does not distinguish LONG_DEAD from DEAD.

See Bike House (Dockless) Integration for access-control-only bike houses, or Bike House (with Docks/Lockers) Integration for bike houses with interior storage devices.

BIKE_DOCK

An outdoor bicycle parking dock. Each dock holds one bicycle using a mechanical locking arm. Docks are the most common Bikeep device type.

Note: Devices may briefly report type: "DOCK" before hardware sync — treat these the same as BIKE_DOCK. Your integration should handle both values.

Available commands

RFID interaction

Same as lockers: tap to lock, tap again to unlock.

SCOOTER_DOCK

A parking dock designed for scooters. Functionally similar to BIKE_DOCK but physically adapted for scooter form factors. Found at SCOOTER_DOCKS locations; the newer-generation SCOOTER_DOCKS_V2 locations use the same device type with the same commands and behavior.

Available commands

lock, unlock, book

BIKE_HOUSE_DOOR (Entrance Door)

A BIKE_HOUSE_DOOR is a physical entrance device at a bike house (bike room, hangar, or dockless space). It is a child of the GUARD and controls the electronic lock on one of the bike house’s entry points. A bike house may have one or more BIKE_HOUSE_DOOR devices — one per physical entrance. Users access the bike room by tapping a whitelisted RFID card on the door’s reader, or via the API unlock command.

Physical behavior

• The door has an electronic lock and an RFID reader
• When a whitelisted RFID card is tapped, the lock releases and the user enters
• The lock re-engages automatically after a timeout
• The API unlock command triggers the same lock release as an RFID tap

Available commands

Key characteristics

• API-controllable: BIKE_HOUSE_DOOR supports the unlock command for remote door access (e.g., from a mobile app)
• RFID access: The BIKE_HOUSE_DOOR’s RFID reader accepts cards allowed by the location’s whitelist
• No sessions: Each unlock is a stateless action — no usage session is created
• No booking: BIKE_HOUSE_DOOR does not support book or cancel-booking
• Inverted availability: A BIKE_HOUSE_DOOR in LOCKED state is “available” (door is secured and ready to be opened)

A note on DOOR vs BIKE_HOUSE_DOOR

The API returns BIKE_HOUSE_DOOR as the device type for bike house entrance doors after hardware sync. You may encounter type: "DOOR" for devices not yet synced with hardware — treat these the same as BIKE_HOUSE_DOOR. Your integration should handle both values.

Common Properties

All devices share these response fields:

Power Save and Sleep

Bikeep devices support power-saving modes to extend battery life and reduce energy consumption. Two fields on every device tell you whether it is asleep and how it can be woken: sleep_state and power_save_strategy.

Strategy comparison:

Sleep states:

Integrator guidance:

• NONE or REMOTE_WAKEUP — safe to send commands at any time. For REMOTE_WAKEUP devices in LIGHT_SLEEP, expect longer initial response times but no code changes needed. Once awake, latency drops to the same levels as non-sleeping devices.
• LOCAL_WAKEUP in DEEP_SLEEP — do not send commands. The device cannot be reached. Wait for sleep_state to change to "" (awake), or inform the end user that physical interaction is required.

heartbeat_v2

The heartbeat_v2 object provides richer connectivity information than the top-level heartbeat_health field. Prefer heartbeat_v2 for new integrations.

Note: heartbeat_v2.health includes LONG_DEAD (device offline for 2+ hours), while the top-level heartbeat_health maps LONG_DEAD → DEAD for backwards compatibility.