SynKink F developer guide

Connect

Wi-Fi

SynKink F always runs its own open Wi-Fi network, called SynKink-F by default. Join it and the device is at http://192.168.4.1. All Wi-Fi routes use plain HTTP on port 80.

To use it on your home network, send your Wi-Fi name and password with POST /api/wifi/connect. The setup network stays on after that.

On your home network, the device gives your router the name SynKink-F. Many routers let you reach it as http://SynKink-F. If yours does not, find its address with GET /api/wifi/status on the setup network.

Bluetooth

In normal mode, SynKink F shows up as SynKink F. Its advertising data holds company ID 0x0FD5, then the bytes 01 00. The 01 marks SynKink F. Look for the company ID and you find the device even after a rename.

You do not need to pair to read data. Connect and subscribe. One app can connect over Bluetooth at a time.

In DID mode it shows up as SynKink F DID and pairs like any keyboard, with no code.

Get a token

Most REST routes need a token. You get one when someone presses the button on the device. This keeps other people on your network out.

1. Ask for a login. The light on the device blinks fast.

   curl http://192.168.4.1/api/auth/request

   {
     "status": "ok",
     "request_id": "cb3031ade64d3a86e0c1ac1cf3a1316ad45ebb085dc3c5f444e609e217e95234",
     "message": "Press the button on your device"
   }

2. Press the button on the device once, within 30 seconds.

3. Ask for the result about once a second, with the request_id from step 1.

   curl "http://192.168.4.1/api/auth/result?id=cb3031ade64d3a86e0c1ac1cf3a1316ad45ebb085dc3c5f444e609e217e95234"

   {"state":"pending"}

   {"state":"granted","token":"d6941d514d2585707d4aa7c1a71cde4bd8b7dfa879f263a1dbdcb3f81bf14a51"}

   Any state other than pending or granted means it did not work. Start again at step 1.

4. Send the token in the Authorization header. Send the token only, with no word in front of it.

   curl -H "Authorization: d6941d514d2585707d4aa7c1a71cde4bd8b7dfa879f263a1dbdcb3f81bf14a51" http://192.168.4.1/api/sensors/current

• The device shows the token once. Save it.
• A token stops working after 10 minutes without use. A restart ends all tokens.
• Up to 4 tokens work at once. A fifth replaces the one used longest ago.
• Only one login can wait for the button at a time. A second one gets status 409.
• GET /api/auth/status with the header tells you if your token still works.

Without a valid token, a route answers with status 401:

{"status":"error","error":"Unauthorized - authentication required"}

REST routes

Use http://192.168.4.1 on the setup network, or the device address on your home network. Requests and answers are JSON. Bodies can be up to 2048 bytes. When a call fails, the answer has "status":"error" and a short reason.

Answers can hold more fields than shown here, so skip the ones you do not need.

Device

{
  "uptime": 523,
  "free_heap": 143212,
  "firmware_version": "1.0.3",
  "hardware_version": "1.24.2",
  "model": "SynKink F",
  "product": "euphoria_f1",
  "device_id": "3485189A2B10",
  "device_name": "SynKink F",
  "ble_enabled": true,
  "captive_enabled": true,
  "wifi_connected": true
}

Sensors

{"timestamp":523114,"sensors":[0,12,140,880,1630,2210,950,40],"sum":5862}

Settings

{
  "device": {
    "name": "SynKink F",
    "ble_name": "SynKink F",
    "ble_hid_name": "SynKink F DID",
    "ap_name": "SynKink-F",
    "hostname": "SynKink-F"
  },
  "audio": {
    "mute": false
  },
  "sleep": {
    "timeout": 600000,
    "enabled": true,
    "sensitivity": 5
  },
  "hid_startup": {
    "enabled": false
  }
}

Wi-Fi

curl -X POST http://192.168.4.1/api/wifi/connect \
  -H "Authorization: d6941d514d2585707d4aa7c1a71cde4bd8b7dfa879f263a1dbdcb3f81bf14a51" \
  -H "Content-Type: application/json" \
  -d '{"ssid":"Home","password":"your-wifi-password"}'

{
  "connected": true,
  "connecting": false,
  "ssid": "Home",
  "ip": "192.168.1.42",
  "rssi": -58,
  "hostname": "SynKink-F"
}

Live stream over WebSocket

Open ws://192.168.4.1/ws, or the same path on the home network address.

Send this to start the sensor stream:

{"type":"subscribe","channel":"sensors"}

You then get a sensor_update every 50 milliseconds, so 20 a second. sensors holds the 8 values. sum adds them up.

{"type":"sensor_update","timestamp":523164,"sensors":[0,12,140,880,1630,2210,950,40],"sum":5862}

Send this to stop it:

{"type":"unsubscribe","channel":"sensors"}

Every client gets two more messages, with or without the stream:

{"type":"button_event","event":"short_press"}

Bluetooth

The device's own services use this base UUID, with the short ID in place of XXXX:

0000XXXX-6136-4d92-9bb7-5bab7345fa61

Sensor data service: 0004

{"timestamp":523120,"values":[0,12,140,880,1630,2210,950,40]}

Button service: 0006

{"event":"short_press","timestamp":523120}

Device information service: 180A

DID keyboard mode

In DID mode, SynKink F works as a Bluetooth keyboard and mouse. Your thrusts and the button send key presses or mouse clicks. It works with any computer or phone that takes a Bluetooth keyboard.

Turn it on and off

• Hold the button for 5 seconds and DID mode turns on or off. Let go before 7 seconds, because at 7 seconds the device turns off.
• Or call POST /api/hid/enable and POST /api/hid/disable.
• To start in DID mode after every restart, call POST /api/config/hid-startup with enabled set to true.

Button presses go to your triggers. Pair from the Bluetooth settings of your computer or phone.

Routes

{
  "events": [
    {
      "timestamp": 523114220,
      "trigger": 0,
      "description": "Click -> Key 0x2C (mod 0x00)"
    }
  ]
}

Triggers

A trigger turns pressure or a button press into a key or a click. There are 11 slots, numbered 0 to 10. Slots 0 to 7 are pressure triggers and use the sum of all 8 sensors. Slots 8 to 10 are button triggers.

Trigger types

Fields

A key or click stays down while the trigger is on, then lets go. For a button press trigger, it stays down while you hold the button.

Modifier keys

Example

Save a trigger that presses Space on a quick thrust:

curl -X POST http://192.168.4.1/api/hid/trigger \
  -H "Authorization: d6941d514d2585707d4aa7c1a71cde4bd8b7dfa879f263a1dbdcb3f81bf14a51" \
  -H "Content-Type: application/json" \
  -d '{"id":0,"name":"Click","trigger_type":0,"output_type":0,"key_code":44,"pressure_min":100,"pressure_max":400,"pressure_time_window_ms":50}'

That slot then looks like this in GET /api/hid/config:

{
  "enabled": true,
  "name": "Click",
  "trigger_type": 0,
  "output_type": 0,
  "key_code": 44,
  "modifier_keys": 0,
  "mouse_button": 0,
  "repeat_enabled": false,
  "repeat_interval_ms": 0,
  "repeat_delay_ms": 0,
  "pressure_min": 100,
  "pressure_max": 400,
  "pressure_time_window_ms": 50,
  "button_press_min_ms": 0,
  "button_press_max_ms": 0,
  "button_multi_window_ms": 0
}

Examples

Read the live stream over WebSocket

This runs in Node.js 22 or newer. Use the home network address if you are not on the setup network.

const ws = new WebSocket('ws://192.168.4.1/ws')

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'subscribe', channel: 'sensors' }))
}

ws.onmessage = (event) => {
  const message = JSON.parse(event.data)
  if (message.type === 'sensor_update') {
    console.log(message.timestamp, message.sensors, message.sum)
  }
}

Read the live stream over Bluetooth

This runs in Python 3 with the bleak package (pip install bleak). It finds SynKink F by its company ID and prints readings for 30 seconds.

import asyncio
import json

from bleak import BleakClient, BleakScanner

SENSOR_VALUES = "00000401-6136-4d92-9bb7-5bab7345fa61"


def on_values(_, data):
    reading = json.loads(data)
    print(reading["timestamp"], reading["values"])


async def main():
    device = await BleakScanner.find_device_by_filter(
        lambda _, adv: 0x0FD5 in adv.manufacturer_data
    )
    async with BleakClient(device) as client:
        await client.start_notify(SENSOR_VALUES, on_values)
        await asyncio.sleep(30)


asyncio.run(main())