PixDot Protocol

简体中文

A portable protocol library and BLE SDKs for compatible smart bead boards.

Important

This project is incubating. Protocol coverage and public APIs may change before the first stable release. Incubating builds use prerelease tags such as v0.3.0-incubating.2.

Supported devices

• 像素糖果: HPD-3232, HPD-5252, HPD-7878, HPD-104104

Packages

• PixDot::Protocol: portable ISO C11 protocol core.
• pixdot-android: Android BLE transport backed by the C core through JNI.
• PixDot: iOS CoreBluetooth SDK backed by the C core through Swift interop.
• @oxyroid/pixdot: Web Bluetooth transport backed by the C core through WASM.
• Protocol reference

Releases

Incubating releases provide the Android AAR, Web npm tarball, portable C core and checksums on GitHub Releases. Android and Web packages are also published to GitHub Packages after CI passes.

Architecture

core is the only protocol implementation. It owns packet encoding, CRC, framing and response parsing. Android, iOS and Web contain platform transport code only. Native, Swift and WASM checks use the same conformance vectors.

Build

./scripts/test-native.sh
./scripts/test-ios.sh
npm --prefix web-sdk test
ANDROID_HOME=/path/to/android-sdk ./gradlew \
  :android-sdk:testDebugUnitTest \
  :android-sdk:assembleRelease

The Android AAR is written to:

android-sdk/build/outputs/aar/android-sdk-release.aar

Native API

#include <pixdot/protocol.h>

uint8_t bytes[5];
pixdot_buffer packet = {bytes, sizeof(bytes), 0};
if (pixdot_encode_brightness(50, &packet) == PIXDOT_OK) {
    /* Write packet.data[0..packet.size) to the board. */
}

All output buffers are caller-owned. Encoders set packet.size to the required size and return PIXDOT_ERROR_BUFFER_TOO_SMALL when capacity is insufficient. Use pixdot_try_board_size_from_device_name or pixdot_try_board_size_from_advertisement when scanning. A false result means the size must be obtained from the board-information response.

Android SDK

val scanner = PixDotDeviceScanner(context)
val client = PixDotClient(context)

scanner.start { device ->
    scanner.stop()
    client.connect(device)
}

See the Android SDK reference for commands and data formats.

iOS SDK

Add this repository as a Swift package, then:

let scanner = PixDotDeviceScanner()

scanner.start(onDevice: { device in
    let client = scanner.makeClient(for: device)
    Task {
        try await client.connect()
        try await client.setBrightness(60)
    }
})

See the iOS SDK reference for Bluetooth permissions, connection and image transfer APIs.

Web SDK

import { PixDotWebClient } from "@oxyroid/pixdot";

const client = await PixDotWebClient.request({
  serviceUuid: "YOUR_SERVICE_UUID",
});
await client.setBrightness(60);

See the Web SDK reference for browser connection and image transfer APIs.

License

Apache-2.0