Device Registration

Device Registration API

Initial device onboarding endpoint to register ESP32C6 + BCGMCU devices and obtain authentication credentials.

Endpoint

POST /api/v1/device/register

Purpose

• Register new devices with the cloud service
• Obtain authentication token for subsequent API calls
• Declare device capabilities and specifications
• Set initial configuration parameters

Request

Headers

Content-Type: application/json
Authorization: Bearer {provisioning_token}

Note: The provisioning token is a one-time token provided during device setup.

Request Body

{
  "device_info": {
    "device_id": "BCGMCU_001",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "hardware_revision": "Rev A",
    "firmware_version": "1.0.0",
    "bcgmcu_serial": "BCG123456789",
    "esp32c6_chip_id": "ESP32C6_ABCDEF"
  },
  "capabilities": {
    "max_streaming_rate": 10,
    "batch_memory_size": 1048576,
    "supported_modes": ["streaming", "batch", "hybrid"],
    "calibration_support": true
  },
  "location": {
    "facility_id": "Hospital_A",
    "room": "ICU_01",
    "bed": "Bed_03"
  }
}

Field Descriptions

device_info

Field	Type	Required	Description
device_id	string	Yes	Unique device identifier
mac_address	string	Yes	WiFi MAC address
hardware_revision	string	No	Hardware version
firmware_version	string	Yes	Current firmware version
bcgmcu_serial	string	Yes	BCGMCU module serial number
esp32c6_chip_id	string	Yes	ESP32C6 chip identifier

capabilities

Field	Type	Required	Description
max_streaming_rate	integer	Yes	Maximum Hz for streaming (1-10)
batch_memory_size	integer	Yes	Available memory for batch storage in bytes
supported_modes	array	Yes	List of supported operation modes
calibration_support	boolean	Yes	Whether device supports remote calibration

location

Field	Type	Required	Description
facility_id	string	No	Facility identifier
room	string	No	Room or ward identifier
bed	string	No	Bed or location identifier

Response

Success Response (200 OK)

{
  "registration_status": "approved",
  "device_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "server_endpoints": {
    "status": "/api/v1/device/status",
    "data_stream": "/api/v1/data/stream",
    "batch_upload": "/api/v1/data/batch",
    "config": "/api/v1/device/config"
  },
  "default_configuration": {
    "streaming_mode": "realtime",
    "streaming_rate": 1,
    "batch_interval": 3600,
    "status_interval": 300
  }
}

Response Fields

Field	Type	Description
registration_status	string	”approved”, “pending”, or “rejected”
device_token	string	JWT token for authentication (24-hour expiration)
server_endpoints	object	Available API endpoints for this device
default_configuration	object	Initial device configuration settings

Error Responses

400 Bad Request

{
  "error": "Invalid request format",
  "details": "Missing required field: device_id"
}

401 Unauthorized

{
  "error": "Invalid provisioning token",
  "details": "Token expired or not recognized"
}

409 Conflict

{
  "error": "Device already registered",
  "device_id": "BCGMCU_001"
}

Implementation Example

ESP32 Arduino

#include <HTTPClient.h>
#include <ArduinoJson.h>

bool registerDevice(String provisioningToken) {
  HTTPClient https;

  // Prepare registration payload
  StaticJsonDocument<1024> doc;

  // Device info
  doc["device_info"]["device_id"] = getDeviceId();
  doc["device_info"]["mac_address"] = WiFi.macAddress();
  doc["device_info"]["firmware_version"] = FIRMWARE_VERSION;
  doc["device_info"]["bcgmcu_serial"] = getBCGMCUSerial();
  doc["device_info"]["esp32c6_chip_id"] = getChipId();

  // Capabilities
  doc["capabilities"]["max_streaming_rate"] = 10;
  doc["capabilities"]["batch_memory_size"] = 1048576;
  JsonArray modes = doc["capabilities"].createNestedArray("supported_modes");
  modes.add("streaming");
  modes.add("batch");
  modes.add("hybrid");
  doc["capabilities"]["calibration_support"] = true;

  // Location (optional)
  doc["location"]["facility_id"] = "Hospital_A";
  doc["location"]["room"] = "ICU_01";

  String payload;
  serializeJson(doc, payload);

  // Send registration request
  https.begin(API_BASE_URL + "/device/register");
  https.addHeader("Content-Type", "application/json");
  https.addHeader("Authorization", "Bearer " + provisioningToken);

  int httpCode = https.POST(payload);

  if (httpCode == 200) {
    String response = https.getString();

    // Parse response
    StaticJsonDocument<512> responseDoc;
    deserializeJson(responseDoc, response);

    String deviceToken = responseDoc["device_token"];

    // Store token securely
    storeDeviceToken(deviceToken);

    // Store endpoints
    storeEndpoints(responseDoc["server_endpoints"]);

    // Apply default configuration
    applyConfiguration(responseDoc["default_configuration"]);

    return true;
  }

  return false;
}

Error Handling

void handleRegistrationError(int httpCode, String response) {
  switch(httpCode) {
    case 400:
      Serial.println("Invalid request format");
      // Fix request and retry
      break;
    case 401:
      Serial.println("Invalid provisioning token");
      // Request new provisioning token
      break;
    case 409:
      Serial.println("Device already registered");
      // Use token refresh endpoint instead
      break;
    case 500:
    case 503:
      Serial.println("Server error - retrying...");
      // Implement exponential backoff
      delay(5000);
      // Retry registration
      break;
  }
}

Security Considerations

1. Provisioning Token: Single-use token that expires after successful registration
2. Device Token: JWT with 24-hour expiration, requires periodic refresh
3. TLS Certificate: Validate server certificate to prevent MITM attacks
4. Secure Storage: Store device token in encrypted NVS partition
5. Token Rotation: Implement automatic token refresh before expiration

Best Practices

1. Unique Device IDs: Use combination of MAC address and chip ID
2. Version Tracking: Include accurate firmware and hardware versions
3. Error Recovery: Implement retry logic with exponential backoff
4. Token Management: Securely store and refresh tokens
5. Location Updates: Update location when device is moved