Entrixy v2 — final architecture

1. Privacy: the server knows nothing (by default)

All sensitive data is kept on the phone only. The owner may optionally pass some of it through the server — with an explicit warning.

2. Four object types

When adding an object the owner picks a connection type. A settings window for that type opens next.

The firmware configurator for the last two types: /controller/ (BLE and Internet, in the browser).

To the user every type looks the same: a card, a Call button, a status. Only the delivery mechanism differs.

3. Webhook (URL) in detail

Two sending modes

The webhook settings window offers a switch, with the pros and cons spelled out on screen:

Where the data lives

Request protocol

Security: an HMAC signature. The device and Entrixy share a webhook_secret.

POST https://device-url.com/open
Content-Type: application/json

{
  "action": "open",
  "object_id": 42,
  "timestamp": 1713020000,
  "nonce": "a1b2c3",
  "signature": "hmac-sha256(secret, timestamp + nonce + action)"
}

The device checks that the signature is valid, the timestamp is under 30 seconds old and the nonce is not a repeat. If all is well it acts and replies:

{"status": "ok", "message": "Door opened"}
or
{"status": "error", "message": "Lock jammed"}

The status is shown to the user in the app.

Data flow (phone mode)

The guest presses Call
  → the server receives the request
  → sends it to the owner over the WebSocket: {type: "do_webhook", ...}
  → the owner's phone makes the HTTP call to the device
  → receives the JSON response
  → sends it to the server: {type: "webhook_result", status, message}
  → the server passes it to the guest
  → both see the status in the log

Logging

In both modes the log on the owner's and the guest's phone records who, when, which object and what status came back.

4. Device (ESP32 / ESP8266, WebSocket) in detail

How it works

The controller — ESP32, ESP32-S3, ESP32-C3 or ESP8266, all supported — has no public IP. It keeps an outbound WebSocket connection to the Entrixy server, exactly as the owner's phone does.

Firmware and configurator live at /esp/socket/. Sources: ESP32, ESP8266.

The device's WebSocket protocol

// Device → server: connect
{"type": "device_hello", "device_key": "xyz789", "device_secret": "..."}

// Server → device: OK
{"type": "device_ok"}

// Server → device: command
{"type": "device_command", "action": "open", "command_id": "abc123"}

// Device → server: result
{"type": "device_response", "command_id": "abc123", "status": "ok", "message": "Opened"}

The server relays the status to the clients — owner and guest — over their WebSocket connections.

Registering a device

1. In the app the owner chooses Add object → type Device
2. This generates device_key + device_secret
3. A QR code with the firmware details is shown
4. The user flashes the ESP32 or ESP8266 (see the configurator) and the device connects to wss://entrixy.com/ws

Indication

The object card shows the device's connection status, online or offline, just as guests see the owner's status.

4a. BLE controller (ESP32) in detail

How it works

A controller on the ESP32, S3, C3, C6 or H2 needs neither Wi-Fi nor a server to fire. It sits in deep sleep, wakes once a second for about 200 ms and broadcasts a BLE advertisement with a signed counter. When a phone holding a valid key comes near, Android — or the app, if it is in the foreground — catches the advertisement, connects over GATT, sends a fire command with a one-time nonce, and the controller closes the relay for a brief pulse. For bistable drives and locks there is a mode with separate open and close and position tracking, where open/closed travels as an encrypted byte in the advertisement.

The Entrixy server plays no part in this channel. It is needed only when a guest key is created: the owner signs a GuestToken and passes it to the guest over the end-to-end encrypted channel. After that the guest works offline.

The BLE protocol in brief

• Pair-flow — ECDH X25519 between phone and controller. The shared secret is derived with HKDF-SHA256 and the key never goes on the air.
• Advertise — manufacturer-specific data, 18 bytes: company ID + device_id + counter + HMAC-SHA256(secret, device_id||counter).
• Fire (owner) — READ nonce → WRITE [nonce || HMAC(secret, nonce)].
• Fire (guest) — WRITE [GuestToken || owner_sig || nonce || guest_sig]. The GuestToken carries a TTL, which the controller checks against its local RTC.
• Time-sync — the owner corrects the RTC with a signed command.

The full protocol specification, bit layout and test vectors are at entrixy.com/ble. The threat model is in a separate document.

When BLE beats WebSocket

• The drive has no reliable Wi-Fi — a gate in a field, a barrier behind a metre of concrete.
• Battery operation is required, with no mains socket nearby.
• You would rather not depend on the internet or our servers at the moment of opening.
• Guests need to open things offline — the controller checks the token itself.

When WebSocket beats BLE

• You need to open remotely, without driving up to the gate.
• Wi-Fi is present and reliable, and so is a mains socket.
• Convenience: add the device, get the device_key and secret in the app, load the program into the controller.

You can fit both BLE and WebSocket to the same drive — they appear as two separate objects in the app. BLE for opening up close without internet, WebSocket for the times you are far away.

Registering a device

1. In the app the owner chooses Add object → type BLE controller
2. The app scans the air for devices in pairing mode (named entrixy-pair)
3. Selecting a device runs an ECDH exchange over GATT; the shared secret is saved in the phone's Prefs and in the controller's NVS
4. No QR code and no button presses — a new device enters pairing mode by itself once the program is loaded

Firmware and configurator live at /esp/ble/. Source: /esp32-example/.

Indication

On the object card: grey means not visible on the air, either too far or switched off; orange means visible but the automation has not fired; green means it fired or is firing; grey with a green outline means it fired recently and can be tapped to open again.

Database

CREATE TABLE devices (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  host_id INT UNSIGNED NOT NULL,
  device_key VARCHAR(64) NOT NULL UNIQUE,
  secret_hash VARCHAR(64) NOT NULL,
  label VARCHAR(128) DEFAULT '',
  last_seen DATETIME NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

In server.php a third WebSocket role is added: device (alongside host and guest).

5. Triggers: GPS and Wi-Fi

GPS and Wi-Fi work independently. With both configured, whichever condition is met first does the firing. The shared cooldown between firings is 20 seconds.

GPS — as it is today

• Coordinates, a radius and an adaptive update interval
• Indication: "312 m"

Wi-Fi — two modes

Mode 1: the Wi-Fi picture (fingerprint)

• The user taps "Remember Wi-Fi" and every visible network is scanned
• The BSSIDs are stored — unique MAC addresses. The SSID is shown in the interface, but what is kept is the BSSID
• The number of networks found is displayed
• The user sets a "minimum matches" threshold, 5 by default
• A warning appears if too few networks were found
• Trigger: at least N of the remembered networks are visible → it fires
• Indication: 📶 with bars — 0 to 4, by how the number of matches compares with the threshold

Mode 2: connected to a network

• A specific Wi-Fi network is bound (BSSID and SSID)
• Trigger: the phone connects to that network
• Zero power cost — it rides on a system broadcast
• Indication: 📶 green or grey

Power consumption

• WifiManager.getScanResults() — cached results with no fresh scan; we call it on every GPS update at no cost
• The connection mode uses NetworkCallback, with no scanning at all

Storage (Prefs, never leaves the phone)

wifi_trigger_<actionKey> = {
  "mode": "fingerprint" | "connect",
  "bssids": ["AA:BB:CC:DD:EE:FF", ...],
  "min_match": 5,
  "connect_bssid": "AA:BB:CC:DD:EE:FF",
  "connect_ssid": "TP-Link_5G",
  "enabled": true
}

6. Three levels of confirmation

The owner decides whether confirmation is required. How identity is confirmed is up to the client, from whatever the device offers.

"Confirm" is not a wasted step. The notification appears in the shade by itself at the right moment. No hunting for the app, no unlocking, no finding the object. One tap and the door is open.

Priority of identity confirmation methods

1. Biometrics, if a sensor exists → BiometricPrompt
2. The phone's PIN or password, when there is no biometrics → KeyguardManager
3. The app's own PIN, on a device with no lock → our own dialog

The time window — an extra factor

The owner sets "Allowed hours: 07:00–23:00". Outside that window the condition is silently ignored. An overnight interval works too (22:00–06:00).

Three independent factors of protection

1. WHERE — GPS, a Wi-Fi fingerprint or a connection
2. WHO — automatic, confirmation or biometrics
3. WHEN — the time window

7. Owner versus guest — splitting the settings

8. The app interface

Adding an object (SettingsScreen)

The first step is choosing a connection type:

┌────────────────────────────┐
│  Connection type           │
│                            │
│  📞  Call                  │
│  Opening with a phone      │
│  call                      │
│                            │
│  🌐  URL                   │
│  Sending a command to      │
│  a device address          │
│                            │
│  📟  Device                │
│  Connected through Entrixy │
│  (ESP32, Arduino)          │
└────────────────────────────┘

After the choice, a settings window for that type opens.

The expanded object card (ActionCard)

┌──────────────────────────────────────────┐
│  Corner barrier             📶 3/5  312m │
│  Mine • ●                                │
├──────────────────────────────────────────┤
│  [Edit]  [Icon]                          │
│  ─────────────────────────               │
│  [📍 Geo]   [📶 Wi-Fi]                   │
└──────────────────────────────────────────┘

The 📍 Geo window

• Radius (a 10–500 m slider)
• A "Detect coordinates" button
• Distance, Google Maps
• Time window: [07:00] — [23:00]
• Confirmation: Automatic / Confirm / Confirm identity

The 📶 Wi-Fi window

◉ By the Wi-Fi picture

• "Remember networks" → "N networks found"
• The match threshold, decided by the user

○ By connection to a network

• The current network → "Bind"

Below: the time window and confirmation, shared with Geo

The webhook window (🌐 URL)

• The device URL
• The secret, generated automatically or entered by hand
• Sending mode (a switch with explanations):

Indication on the collapsed card

9. Plan limits

Internal plans. They are not shown to the user, but the limits apply.

On exceeding it, a gentle message: "The number of objects is limited. Contact support to raise it."

CREATE TABLE plans (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(64) NOT NULL,
  max_numbers INT NOT NULL DEFAULT 10,
  max_keys INT NOT NULL DEFAULT 10
);
INSERT INTO plans (name) VALUES ('default');

ALTER TABLE hosts ADD COLUMN plan_id INT UNSIGNED DEFAULT 1;

10. Database — the full set of changes

-- Plans
CREATE TABLE plans (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  name VARCHAR(64) NOT NULL,
  max_numbers INT NOT NULL DEFAULT 10,
  max_keys INT NOT NULL DEFAULT 10
);
INSERT INTO plans (name) VALUES ('default');

ALTER TABLE hosts ADD COLUMN plan_id INT UNSIGNED DEFAULT 1;

-- Object type and settings
ALTER TABLE numbers
  ADD COLUMN type ENUM('call','webhook','device') DEFAULT 'call',
  ADD COLUMN radius INT DEFAULT 80,
  ADD COLUMN time_from TIME NULL,
  ADD COLUMN time_to TIME NULL,
  ADD COLUMN security_level ENUM('auto','confirm','identity') DEFAULT 'auto',
  ADD COLUMN geo_available TINYINT(1) DEFAULT 1,
  ADD COLUMN wifi_available TINYINT(1) DEFAULT 1,
  ADD COLUMN wifi_min_match INT DEFAULT 5,
  ADD COLUMN share_lat DOUBLE NULL,
  ADD COLUMN share_lon DOUBLE NULL,
  ADD COLUMN webhook_url VARCHAR(512) NULL,
  ADD COLUMN webhook_secret VARCHAR(64) NULL,
  ADD COLUMN webhook_mode ENUM('phone','server') DEFAULT 'phone',
  ADD COLUMN device_id INT UNSIGNED NULL;

-- Devices (ESP32)
CREATE TABLE devices (
  id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  host_id INT UNSIGNED NOT NULL,
  device_key VARCHAR(64) NOT NULL UNIQUE,
  secret_hash VARCHAR(64) NOT NULL,
  label VARCHAR(128) DEFAULT '',
  last_seen DATETIME NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

share_lat / share_lon — filled in only when the owner has enabled "Share coordinates with guests".

webhook_url / webhook_secret — filled in only in server mode. In phone mode they live in Prefs.

11. Object icons for guests

The owner sets a custom icon on an object and the guest should see it. But the icon is not stored on the server — the server acts as a postman: it delivers and forgets.

Preparation on the owner's side

When the icon is set it is immediately shrunk to 64×64 PNG (about 3–5 KB) and kept locally in Prefs or a file.

How it travels

1. The guest connects
   → guest_ok carries has_avatar: true for objects that have an icon

2. The guest client checks: has_avatar=true but no icon locally?
   → Yes → it asks the server

3. The server has no icon
   → it asks the owner over the WebSocket: {type: "avatar_request", number_id: 42}

4. The owner's phone
   → reads the local file
   → sends: {type: "avatar_data", number_id: 42, data: "base64..."}

5. The server passes it to the guest
   → {type: "avatar_data", number_id: 42, data: "base64..."}

6. The guest stores it locally and never asks again

7. The server stored nothing — the data merely passed through

Edge cases

12. Load forecast

One active owner generates

• 1 WebSocket connection, permanent, with ping/pong every 30 s
• 1 HTTP host_sync at start-up
• 1 HTTP promo every 15 minutes (cache_ttl)
• 5–10 calls a day, one WebSocket frame each

One active guest

• 1 WebSocket connection
• 1–3 calls a day

Scaling

Workerman on a single worker: 5,000–10,000 concurrent connections, at roughly 20 KB each.

Webhook and Device

• A webhook from the server — one HTTP request per call. 10,000 subscribers × 5 calls a day = 50,000 requests a day, about 0.6 a second
• Device — one extra permanent WebSocket connection per device

The bottleneck

is MySQL, not the WebSockets. But 250,000 inserts a day — 50k subscribers × 5 calls — is nothing for MySQL on an SSD.

13. Implementation plan

1. Database — plans, the new columns in numbers and hosts, the devices table
2. Server-side limits — checks in number_add and key_create
3. Object type — choosing a type when adding, with different dialogs
4. API — host_sync and guest_ok with the new profile fields
5. Webhook — the HMAC protocol, two sending modes, the response status
6. Device WS — device_hello, device_command and device_response in server.php
7. The Wi-Fi trigger — fingerprint and connection
8. Time window — time_from/time_to
9. Confirmation — three levels: automatic, confirm, confirm identity
10. Icons — transit delivery over the WebSocket, compressed to 64×64
11. UI — the Geo and Wi-Fi buttons, the dialogs, the indicators, the type picker
12. Sharing coordinates — an option with a warning
13. Build and release