Skip to main content

HxTP Protocol

HxTP is a set of rules for how devices and the cloud talk to each other. Think of it like a formal handshake — both sides agree on the rules so nothing gets lost or misunderstood.

Why Rules Matter​

In a smart home, a misunderstood message could mean a door stays unlocked or a heater stays on when it shouldn't. HxTP makes sure every message is:

  • Authentic — it came from who it says it came from
  • Fresh — it wasn't recorded and replayed later
  • Intact — nobody tampered with it in transit
  • Ordered — messages arrive in the right sequence

The Message Format​

Every HxTP message is a single line with 11 pieces of information, separated by pipe characters (|):

version|device_id|tenant_id|client_id|message_id|request_id|sequence_number|timestamp|nonce|message_type|payload_hash

Here's what that looks like with real data:

HxTP/3.1|dev-789|ten-abc|cli-def|msg-123|req-456|101|1713984000|abc123|command|a1b2c3...

Each field follows strict rules so every device — from a tiny sensor to a powerful server — reads the message exactly the same way.

The 7-Step Security Check​

Every incoming message goes through a 7-step security check. If even one step fails, the message is rejected instantly.

  1. Version — Are we speaking the same language? (must be HxTP/3.1)
  2. Timestamp — Was this sent recently? (prevents old messages from being reused)
  3. Size — Is the message too big?
  4. Nonce — Have we seen this exact message before? (prevents replay attacks)
  5. Hash — Does the content match its fingerprint? (tamper check)
  6. Sequence — Are messages in the right order?
  7. Signature — Is the Ed25519 digital signature valid? (identity check)

The HELLO Handshake​

Before a device can do anything, it must complete a simple introduction:

Device → "Hello, my public key is X"  (HELLO)
Cloud  → "Hello back, I trust you"    (HELLO_ACK)
Device → Now it's ACTIVE and ready

This handshake happens automatically — you never need to think about it. The device just won't respond to commands until it's complete.

Signatures (The Digital Wax Seal)​

Every message is signed with Ed25519 — the same technology used in modern secure systems. Think of it like a wax seal on an old letter:

  • You seal the letter with your unique ring → nobody can open it without breaking the seal
  • The recipient checks the seal → they know it's really from you
  • If the seal is broken → the message is thrown away
// This is what happens behind the scenes
const signature = signEd25519(privateKey, canonicalString);
const isValid = verifyEd25519(publicKey, canonicalString, signature);

The Device Lifecycle​

A device only accepts commands when it's ACTIVE.

Next: Learn about Security or try the Quick Start.