Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hologram.io/llms.txt

Use this file to discover all available pages before exploring further.

The Hologram Socket API provides a low-level TCP socket interface for embedded devices to communicate with the Hologram Cloud. The Hologram REST API offers much of the same functionality, but the Socket API is preferable in bandwidth-constrained environments.

​
Connect and Authenticate

Establish a TCP connection to the following host and port and send an API message followed by two newline characters. The API server will close connections after a few seconds of inactivity.
  • Host: cloudsocket.hologram.io
  • Port: 9999
Socket API credentials are associated with a Hologram device. From a device’s dashboard page, generate or view the Cloud Services Router credentials under Receive from Device. The credentials consist of a 8-byte device key.
Note: Use unique Device Credentials for each device.

​
Send a Message to the Hologram Cloud

Send a JSON message with the following fields. Field names have two forms: a full word for better readability, and an abbreviated key for minimizing data usage.
  • devicekey (k) – String. Eight-character Device Key used for authentication
  • data (d) – String. Message payload
  • tags (t) – String or array of strings. Topic or topics (formerly tags) to attach to the message. The server automatically adds the device’s unique topic string (_DEVICE_XXXXX_), and potentially other system topics. Topics should be less than 32 characters and contain only alphanumeric characters, hyphens, underscores or slashes. No spaces.
Note: You may not mix and match full and abbreviated keys within a single JSON message. In other words, you must use either the full keywords or abbreviated keys for all fields in a JSON message.
On success, the server will return the text [0,0] and then close the connection. On error, the server will return a different message, or it may close the connection with no response.

​
Response codes

The server responds with an array of two numbers. The first describes any errors, and the second is currently always set to zero. The first digit maps to the following response codes:
  • 0 – Send successful, no error
  • 1 – Connection was closed so we couldn’t read enough
  • 2 – Couldn’t parse the message
  • 3 – Auth section of message was invalid
  • 4 – Payload type was invalid
  • 5 – Protocol type was invalid
  • 6 – An internal error occurred
  • 7 – Metadata section of message was formatted incorrectly
  • 8 – Topic contained invalid characters or was too long

​
Examples

{
  "k": "********",
  "d": "Hello, world!",
  "t": ["TOPIC1","TOPIC2"]
}
Abbreviated: 
{
  "k":"********",
  "d":"Hello, world!",
  "t":["TOPIC1","TOPIC2"]
}