Device Activation Process

Overview

The device activation process is responsible for verifying device identity and obtaining necessary configuration information. The system supports two activation protocols (v1 and v2), with the v2 protocol using a security verification mechanism based on HMAC-SHA256.

System Initialization Phases

Phase Breakdown

System initialization is divided into three main phases:

1. Device Fingerprint Phase: Prepare device identity information
2. Configuration Management Phase: Initialize the configuration manager
3. OTA Configuration Phase: Obtain server configuration

Phase 1: Device Fingerprint

The DeviceFingerprint class collects and manages device identity information:

• Generate or load a device serial number
• Create or retrieve the HMAC key
• Manage local activation state
• Obtain a standardized MAC address

The device fingerprint file is stored in config/efuse.json and contains:

{
  "serial_number": "SN-xxxxxxxxxxxxxxxx",
  "hmac_key": "64-character hex string",
  "mac_address": "xx:xx:xx:xx:xx:xx",
  "activated": false
}

Phase 2: Configuration Management

Initialize the configuration manager and ensure critical configuration items:

• Initialize CLIENT_ID (UUID format)
• Set DEVICE_ID from device fingerprint (MAC address)
• Verify configuration integrity

Phase 3: OTA Configuration

Request configuration information from the OTA server:

Request URL: SYSTEM_OPTIONS.NETWORK.OTA_VERSION_URL

Request Headers:

Device-Id: MAC address
Client-Id: Client UUID
Content-Type: application/json
User-Agent: board_type/app_name-version
Accept-Language: zh-CN
Activation-Version: version (v2 protocol only)

Request Body:

{
  "application": {
    "version": "app version",
    "elf_sha256": "HMAC key"
  },
  "board": {
    "type": "device type",
    "name": "app name",
    "ip": "local IP",
    "mac": "MAC address"
  }
}

Activation State Analysis

The system analyzes the state based on local activation status and server response:

State Combination Handling

1. Locally not activated + Server returns activation data: Activation process required
2. Locally activated + Server has no activation data: Device is already activated
3. Locally not activated + Server has no activation data: Auto-repair local state
4. Locally activated + Server returns activation data: State inconsistency, may need re-activation

Server Response Format

Response when configuration is successfully obtained:

{
  "mqtt": {
    "endpoint": "MQTT server address",
    "client_id": "MQTT client ID",
    "username": "username",
    "password": "password",
    "publish_topic": "publish topic"
  },
  "websocket": {
    "url": "WebSocket server URL",
    "token": "access token"
  }
}

Response when activation is required:

{
  "activation": {
    "message": "activation prompt message",
    "code": "6-digit verification code",
    "challenge": "random string for HMAC signature",
    "timeout_ms": 30000
  }
}

v2 Protocol Activation Process

Activation Trigger Conditions

When the system analysis determines that activation is needed, it starts the activation process:

1. Check device serial number and HMAC key
2. Display the verification code to the user
3. Play a voice prompt
4. Execute HMAC signature verification

HMAC Signature Calculation

Sign the challenge using the HMAC-SHA256 algorithm:

signature = hmac.new(
    hmac_key.encode('utf-8'),
    challenge.encode('utf-8'),
    hashlib.sha256
).hexdigest()

Activation Request

Request URL: OTA_VERSION_URL + "activate"

Request Headers:

Activation-Version: 2
Device-Id: MAC address
Client-Id: Client UUID
Content-Type: application/json

Request Body:

{
  "Payload": {
    "algorithm": "hmac-sha256",
    "serial_number": "device serial number",
    "challenge": "server challenge",
    "hmac": "HMAC signature"
  }
}

Response Handling

• HTTP 200: Activation successful, update local activation state
• HTTP 202: Waiting for user to enter verification code, continue polling
• HTTP 4xx: Activation failed, log error information

Retry Mechanism

The activation request uses a long-polling mechanism:

• Maximum retry count: 60
• Retry interval: 5 seconds
• Total timeout: 5 minutes
• Replays the verification code prompt on each retry

User Interface Integration

GUI Mode

The ActivationWindow class provides a graphical interface:

• Display verification code
• Show activation status feedback
• Support cancellation of activation
• Asynchronously wait for activation to complete

CLI Mode

The CLIActivation class provides a command-line interface:

• Output verification code to console
• Voice playback of verification code
• Show activation progress

Security Mechanisms

1. Unique Device Identifier: Generate a unique serial number based on hardware information
2. HMAC-SHA256 Signature: Prevent forged activation requests
3. Verification Code: Manual user input confirms device ownership
4. Long-Polling Mechanism: Adapts to network conditions, avoids frequent requests

Configuration Updates

After successful activation, the system automatically updates configuration:

• MQTT connection information
• WebSocket connection information
• Local activation state flag

After configuration update is complete, the application continues the normal startup process.