Skip to content

Instantly share code, notes, and snippets.

@gregopet

gregopet/gist:49a03d91175be9048e9afdeea2900640

Created October 5, 2023 08:58
Show Gist options
  • Save gregopet/49a03d91175be9048e9afdeea2900640 to your computer and use it in GitHub Desktop.
Save gregopet/49a03d91175be9048e9afdeea2900640 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
gistfile1.txt
openapi: 3.0.0
info:
version: 1.0.0
title: Smart City Bikes station protocol
paths: {}
# No specific paths - one of the events below is either sent via MQTT or pushed via TCP to an IP & port
components:
schemas:
GenericEvent:
description: Common properties present in all station events (see individual subtypes)
discriminator:
propertyName: Type
properties:
Station:
description: The ID of this station, matching the backend's station_hardware.serial_no data
type: string
example: "03160003"
Version:
description: Version of the protocol, currently always "1.0"
type: string
example: "1.0"
Timestamp:
description: The local timestamp at which the event was generated
type: string
format: datetime
example: 2023-09-03T20:21:17.826+02:00
EventID:
description: A unique identifier of this message; it has no meaning but it must _not_ repeat for this station (the server should discard messages with duplicate event IDs). Only present in the MQTT version of the protocol.
type: string
example: "123123123"
Type:
description: Type of event
type: string
enum:
- CPU_Info
- CPU_Connect
- RFID_Info
- RFID_Read
- Lock_Info
- Lock_Event
- Status
CPU_Info:
description: A message describing the station's current state
allOf:
- $ref: '#/components/schemas/GenericEvent'
- type: object
properties:
Event:
type: object
properties:
Cpu:
description: A map of properties describing the current state of the CPU
type: object
Location:
description: A map of properties describing the station's location
type: object
PowerSupply:
description: A map of properties describing the current state of the power supply
type: object
CPU_Connect:
description: The event sent by the CPU when it connects / reconnects to the server
allOf:
- $ref: '#/components/schemas/GenericEvent'
- type: object
properties:
Event:
type: object
properties:
ServerIP:
description: IP of the server this CPU will connect to
type: string
ServerPort:
description: port on the server to which this CPU will connect
type: string
LogReset:
description: FIFO reset request?
type: string
LogCount:
description: Number of unsent events in the FIFO queue
type: string
Action:
type: string
enum:
- connect
- disconnect
RFID_Info:
description: A descriptor of all RFID readers on the station itself (not the locks)
allOf:
- $ref: '#/components/schemas/GenericEvent'
- type: object
properties:
Event:
type: object
properties:
RFID:
description: A descriptor of the RFID scanners connected to the system
type: array
items:
type: object
properties:
dev:
description: The device's port
type: string
gpio_power:
description: The device's GPIO power control
type: string
frequency:
description: Frequency the reader operates on, e.g. '125 kHz' or '13.56 MHz'
type: string
example: 13.56 MHz
type:
description: Card type, e.g. "EM4100" or "ISO_UID"
type: string
example: EM4100
RFID_Read:
description:
Result of a RFID read request triggered by a 'rfid read [TIMEOUT]' command. Not used since RFID reads are
handled locally to avoid the connection roundtrip time.
allOf:
- $ref: '#/components/schemas/GenericEvent'
- type: object
properties:
Event:
type: object
properties:
RFID:
description:
Tags read by the readers - nulls indicate that specific reader has read in nothing.
The order of the read IDs corresponds is aligned with the RFID readers listed by a RFIDInfoEvent.
type: array
items:
type: string
example: ["0300CADC20"]
Lock_Info:
description: State of all the locks connected to the station
allOf:
- $ref: '#/components/schemas/GenericEvent'
- type: object
properties:
Event:
type: object
properties:
Lock:
description: Current state of all the locks from this station
type: array
items:
$ref: '#/components/schemas/Lock'
Lock_Event:
description: An event happened on one of the station's locks
allOf:
- $ref: '#/components/schemas/GenericEvent'
- type: object
properties:
Event:
type: object
properties:
Cause:
description: What was the cause for this event being sent?
type: string
enum:
- Lock_Reboot # Lock has rebooted
- Unlock_Checkout # The given RFID tag was taken from lock
- Unlock_Cancel # Unlocked RFID tag was not taken, cancel button was pressed
- Unlock_Timeout # Unlock button was not pressed, timeout reached
- Unlock_Timeout_Checkout # RFID tag was not removed from lock after button was pressed, timeout reached
- Lock_Checkin # RFID tag was returned into the lock
- Lock_Checkin_Timeout # RFID tag return process timed out
- Lock_Checkin_Cancel # RFID tag return process canceled either by button press or incorrect return procedure
- Lock_Error_Set # Lock malfunction started (microswitch or RFID error)
- Lock_Error_Reset # Lock malfunction ended (microswitch or RFID error)
- Lock_Tamper_Set # Lock was tampered with (state started)
- Lock_Tamper_Reset # Lock was tampered with (state ended)
- Lock_Offline_Set # Communication with lock lost
- Lock_Offline_Reset # Communication with lock regained
- Lock_Bike_Status # Returns state of charging electronics, triggered by a LOCK STATUS command */
- Lock_Bike_Connected # Bike was just connected to charger */
- Lock_Bike_Charge_Start # Bike started charging normally */
- Lock_Bike_FullCharge_Start # Bike started a full charge cycle which should not be interrupted by rentals */
- Lock_Bike_Charge_Stop # Bike stopped charging */
- Lock_Bike_Error_Charger # Charger voltage not OK, maintenance should check it out */
- Lock_Bike_Error_Connect # Station could not connect to bike, maintenance should check it out */
- Lock_Bike_Error_Battery # Battery looks problematic and should not be used for rentals, maintenance should check it out */
- Lock_Bike_Error_Charg # Some error occured while charging, but does not seem critical enough to block the bike
Lock:
$ref: '#/components/schemas/Lock'
Status:
description: The result of 'status get' and 'status request PERIOD' commands. Currently isn' t in actual use.
allOf:
- $ref: '#/components/schemas/GenericEvent'
- type: object
properties:
Event:
type: object
properties:
CPU:
description: A map of properties describing the current state of the CPU
type: object
PowerSupply:
description: A map of properties describing the current state of the power supply
type: object
LCD:
description: A map of properties describing the current state of the LCD screen
type: object
Lock:
description: Descriptor of the locks state at the moment of the event
type: object
properties:
status:
type: string
enum:
- Online
- Offline
- Error
- Disabled
- Standby
# Charging statuses, implying the lock is also Online
- Connecting
- Connected
- ConnectError
- Charge
- Charging
- Charged
- ChargeError
- ConnectErrorAlert
- ChargeErrorAlert
example: Online
addr:
description: The address of the lock on the locks bus, seems to be its 0-based index
type: string
example: "6"
id:
description: The lock's index, 1-based, also the lock's "name"
type: number
example: 7
fw:
description: The firmware version of this lock
type: string
example: "001"
dev:
description: The lock's Linux device path
type: string
example: /dev/ttyS1
tag:
description: The RFID tag currently present in the lock
type: string
example: 000038480F
sn:
description: The lock's serial number, unique in the system
type: string
example: "00220124"
type:
description: Type / variant of lock
type: string
example: MMIbis
led:
description: A descriptor of the lock's LED light
type: object
properties:
color:
description: The LED's color, described as 0 - run, 1 - error, 2 - status
type: number
example: 0
mode:
description:
The LED's display mode, described as
0 - off, 1 - very slow power save, 2 - slow power save, 3 - fast power save
4 - slow, 5 - fast, 6 - on
type: number
example: 0
input:
description: The state of the lock's inputs
type: object
properties:
lock:
description: Is the lock currently closed / locked?
type: number
example: 0
button:
description: Was the button pressed?
type: number
example: 0
pin:
description: Is there an RFID pin in the lock?
type: number
example: 1
tamper:
description: Status of the tamper sensor, 1 - OK, 0 - casing is open
type: number
example: 1
GenericCommand:
description:
Elements common to all commands. Commands are a combination of command_pre and command, all possible values are listed below
"cpu", "info" - send a CpuInfo event
"cpu", "connect" - send a CpuConnect event (has parameters)
"cpu", "disconnect" - stop sendin events
"rfid", "read" - start listening for RFID card events for a certain time
"rfid", "info" - list the RFID readers installed on the station
"lock", "unlock" - unlock one or more locks (has parameters)
"lock", "quickunlock" - unlock a lock without requiring a button push (has parameters)
"lock", "powerunlock" - unlock a lock by power cycling its power
"lock", "powerunlockline" - unlock an entire line of locs (has parameters)
"lock", "info" - request a Lock_Info event
"lock", "reset" - reset all locks by cycling their power
"lock", "init" -
"ebike", "connect" - the bike connected to a lock is an ebike and can be charged (has parameters)
"ebike", "disconnect" - stop considering a bike as an ebike (stop charging it for example - has parameters)
"lock", "enable" - enable or disable the lock & update its LED color accordingly (has parameters)
"lock", "test" - not entirely sure what this command does
"status", "get" - transmit a StatusEvent from onboard memory (but don't scan now)
"status", "request" - request a periodic retransmission of the station's state (has parameters)
"status", "read" - instructs the CPU to query the system state and send a StatusEvent
type: object
properties:
command_pre:
description: The general "class" of the command
type: string
enum:
- cpu
- rfid
- lock
- ebike
- status
command:
description: The exact command, its possible values depend on the command_pre attribute (see the description of this command)
type: string
command_id:
description: A unique command ID - the server guarantees this ID will not repeat for any command
type: string
example: "4002230007812183662"
execute_limit:
description:
The upper limit until which this command is to be executed; if the CPU receives it later,
the command should be silently discarded
type: string
format: datetime
example: "2023-09-22T11:36:26+00:00"
data:
description: A key/value pair of parameters to be sent with some commands
type: object
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment