Lightbug Documentation

Appearance

Device WebSocket​

GET
/chasm/ws/{device}

Establishes a WebSocket connection to send and receive messages from a single device

🧪 Alpha

This endpoint is alpha, and may change while being tested.

This documentation page also does not lend itself to a websocket endpoint, this is not a GET. Please see schema descriptions and various response codes for detailed examples of messages.

Supports multiple encoding formats: json, hex, decimal, base64

Authorizations​

ApiKeyAuth

API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See Authentication for more details.

Type
API Key (header: Authorization)
Example"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Parameters​

Path Parameters

device*

Device ID or identifier

Type
string
Required

Query Parameters

encoding

Message encoding format (json|hex|decimal|base64)

Type
string
Default
"json"

Request Body​

application/json
JSON
{
  
"data": "03 18 00 05 00 02",
  
"encoding": "hex",
  
"messageId": "msg-123",
  
"type": "out"
}

Request example

Responses​

Incoming message from device

application/json
JSON
{
  
"data": "a5 b2 c3 d4",
  
"encoding": "hex",
  
"timestamp": "2024-01-10T15:30:45.123Z",
  
"type": "in"
}
Try this endpoint

Playground​

Authorization
Variables
Key
Value
Body

OpenAPI definition ​

References are expanded below, except recursive definitions and references with sibling fields. Documentation overrides are included. Full original OpenAPI spec (JSON).

View endpoint OpenAPI definition
yaml
info:
  title: Lightbug API
  version: '2'
externalDocs:
  description: ''
  url: ''
openapi: 3.1.0
servers:
  - url: https://api.lightbug.cloud/v2
security:
  - ApiKeyAuth: []
tags: []
paths:
  /chasm/ws/{device}:
    get:
      description: |-
        Establishes a WebSocket connection to send and receive messages from a single device

        <div class="custom-block alpha">
        <p class="custom-block-title">🧪 Alpha</p>
        This endpoint is alpha, and may change while being tested.

        This documentation page also does not lend itself to a websocket endpoint, this is not a GET. Please see schema descriptions and various response codes for detailed examples of messages.
        </div>

        Supports multiple encoding formats: json, hex, decimal, base64
      parameters:
        - description: Device ID or identifier
          in: path
          name: device
          required: true
          schema:
            type: string
        - description: Message encoding format (json|hex|decimal|base64)
          in: query
          name: encoding
          schema:
            default: json
            type: string
requestBody:
yaml
        content:
          application/json:
            schema:
              properties:
                data:
                  description: Message data in specified encoding
                  example: 03 18 00 05 00 02
                  type: string
                encoding:
                  description: 'Encoding format: hex, decimal, base64, json'
                  example: hex
                  type: string
                messageId:
                  description: Client-provided message ID for tracking
                  example: msg-123
                  type: string
                type:
                  description: '"out" to send message to device'
                  example: out
                  type: string
              type: object
        description: Message to send to device
        required: true
yaml
      responses:
'101':
yaml
          content:
            application/json:
              schema:
                properties:
                  data:
                    description: Message data in requested encoding
                    example: a5 b2 c3 d4
                  encoding:
                    description: Encoding format
                    example: hex
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:45.123Z'
                    type: string
                  type:
                    description: '"in" - message from device'
                    example: in
                    type: string
                type: object
          description: Incoming message from device
'102':
yaml
          content:
            application/json:
              schema:
                properties:
                  data:
                    description: Server event data
                  encoding:
                    description: Encoding format
                    example: hex
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:46.234Z'
                    type: string
                  type:
                    description: '"srv" - server event'
                    example: srv
                    type: string
                type: object
          description: Server event
'103':
yaml
          content:
            application/json:
              schema:
                properties:
                  messageId:
                    description: Echoes the messageId from request
                    example: msg-123
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:45.200Z'
                    type: string
                  type:
                    description: '"ack" - acknowledgment'
                    example: ack
                    type: string
                type: object
          description: Acknowledgment of sent message
'104':
yaml
          content:
            application/json:
              schema:
                properties:
                  error:
                    description: Error description
                    example: 'failed to parse message: invalid hex data'
                    type: string
                  messageId:
                    description: MessageId from request if available
                    example: msg-123
                    type: string
                  timestamp:
                    description: Server timestamp
                    example: '2024-01-10T15:30:45.150Z'
                    type: string
                  type:
                    description: '"error" - error response'
                    example: error
                    type: string
                type: object
          description: Error response
yaml
      security:
        - ApiKeyAuth: []
      summary: Device WebSocket
      tags:
        - chasm
      operationId: get-chasm-ws-device
components:
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
      description: API Key for authentication. Retrieval from either API version login routes, or other authentication token type. See <a href='/apis/authentication'>Authentication</a> for more details.
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...