117 lines
3.6 KiB
Markdown
117 lines
3.6 KiB
Markdown
# Device Bootstrap And Binding Receipt
|
|
|
|
## Purpose
|
|
|
|
The device-level bootstrap/binding handshake maps a factory IMEI to Banban's
|
|
internal `device_id` and `serial_number`. Its successful `msg_id=012` response
|
|
is the device binding success receipt and includes the associated ICCID for
|
|
downstream SIM/traffic binding. Devices do not need to know those IDs before
|
|
the first handshake.
|
|
|
|
## Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
autonumber
|
|
participant Factory as Factory Excel / import CSV
|
|
participant Mapping as device_imei_mapping
|
|
participant Device as TalkingQ device
|
|
participant MQTT as MQTT broker
|
|
participant Handler as TalkingQMQTTService
|
|
participant Init as device_identity_initializer
|
|
participant Auth as device_auth
|
|
|
|
Factory->>Mapping: Insert imei, device_id, serial_number, status=pending
|
|
Device->>MQTT: Publish device/{imei}/event msg_id=012 binding request
|
|
MQTT->>Handler: Deliver identity init event
|
|
Handler->>Init: initialize_by_imei(imei)
|
|
Init->>Mapping: SELECT mapping by imei
|
|
alt mapping missing or incomplete
|
|
Init-->>Handler: DeviceIdentityInitializationError
|
|
Handler-->>MQTT: device/{imei}/event_resp status=failed
|
|
else mapping found
|
|
Init->>Auth: SELECT device_auth by device_id
|
|
alt no auth row
|
|
Init->>Auth: INSERT device_id, serial_number, is_active=1
|
|
else auth row exists and serial matches
|
|
Init->>Auth: UPDATE is_active=1
|
|
else serial mismatch
|
|
Init-->>Handler: device_auth serial_number conflict
|
|
Handler-->>MQTT: device/{imei}/event_resp status=failed
|
|
end
|
|
Init->>Mapping: UPDATE status=activated, activated_at=now
|
|
Handler-->>MQTT: device/{imei}/event_resp binding success receipt
|
|
MQTT-->>Device: Receive device_id, device_sn, and iccid
|
|
end
|
|
```
|
|
|
|
## Binding Success Receipt
|
|
|
|
When the IMEI mapping and its authoritative ICCID association are available,
|
|
the handler returns the device binding success receipt on `msg_id=012`:
|
|
|
|
```json
|
|
{
|
|
"msg_id": "012",
|
|
"params": {
|
|
"device_id": "TalkingQ_ZHWK00002110",
|
|
"device_sn": "TQ_ZHWK000000002110",
|
|
"iccid": "898604E91123D1334901"
|
|
}
|
|
}
|
|
```
|
|
|
|
The `iccid` value is the canonical, full ICCID used by the downstream SIM and
|
|
traffic service. It must come from an authoritative IMEI-to-ICCID provisioning
|
|
record or a validated device report; it must not be derived from the IMEI.
|
|
Successful device binding requires a non-empty, valid ICCID. If the ICCID
|
|
cannot be resolved or fails consistency validation, the handler must return
|
|
the existing `msg_id=012` failure response instead of returning a partial
|
|
success.
|
|
|
|
Adding `params.iccid` is an additive response-field change. Devices that ignore
|
|
unknown JSON fields remain compatible, while strict firmware parsers need a
|
|
protocol/version capability check before this response is enabled for them.
|
|
|
|
## Data Model
|
|
|
|
```mermaid
|
|
erDiagram
|
|
device_imei_mapping {
|
|
int id PK
|
|
varchar imei UK
|
|
varchar device_id UK
|
|
varchar serial_number
|
|
varchar status
|
|
datetime activated_at
|
|
datetime created_at
|
|
datetime updated_at
|
|
}
|
|
|
|
device_auth {
|
|
int id PK
|
|
varchar device_id UK
|
|
varchar serial_number
|
|
varchar batch_id
|
|
tinyint is_active
|
|
datetime created_at
|
|
datetime updated_at
|
|
}
|
|
|
|
device_imei_mapping ||--o| device_auth : activates
|
|
```
|
|
|
|
## Current ID Style
|
|
|
|
```text
|
|
device_id: TalkingQ_ZHWK00002001
|
|
serial_number: TQ_ZHWK000000002001
|
|
```
|
|
|
|
## Source Anchors
|
|
|
|
- Bootstrap handler: `talkingq-url/handlers/mqtt_handler.py`
|
|
- Identity initializer: `talkingq-url/services/device_identity_initializer.py`
|
|
- Import script: `talkingq-url/scripts/import_device_imei_mapping.py`
|
|
- Tables: `database/talkingq_shared_schema.sql`
|