Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
.DS_Store
.build/
.gradle/
.kotlin/
.idea/
build/
**/build/
Expand Down
9 changes: 8 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ A portable protocol library and BLE SDKs for compatible smart bead boards.
> 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.
Expand Down Expand Up @@ -64,6 +68,9 @@ if (pixdot_encode_brightness(50, &packet) == PIXDOT_OK) {

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

Expand All @@ -73,7 +80,7 @@ val client = PixDotClient(context)

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

Expand Down
9 changes: 8 additions & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@
> 本项目仍在孵化,首个稳定版本发布前,协议覆盖范围和公开 API 可能调整。
> 孵化版本使用 `v0.3.0-incubating.2` 形式的预发布 tag。

## 支持设备

- 像素糖果:`HPD-3232`、`HPD-5252`、`HPD-7878`、`HPD-104104`

## 组件

- `PixDot::Protocol`:可移植的 ISO C11 协议核心。
Expand Down Expand Up @@ -62,6 +66,9 @@ if (pixdot_encode_brightness(50, &packet) == PIXDOT_OK) {

输出缓冲区由调用方持有。编码器会写入所需的 `packet.size`;容量不足时返回
`PIXDOT_ERROR_BUFFER_TOO_SMALL`。
扫描时使用 `pixdot_try_board_size_from_device_name` 或
`pixdot_try_board_size_from_advertisement`。返回 `false` 表示需要通过板信息
响应取得尺寸。

## Android SDK

Expand All @@ -71,7 +78,7 @@ val client = PixDotClient(context)

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

Expand Down
6 changes: 5 additions & 1 deletion android-sdk/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ val client = PixDotClient(context, object : PixDotClientListener {
scanner.start(
callback = { device ->
scanner.stop()
client.connect(device.bluetoothDevice)
client.connect(device)
},
onError = { error -> handle(error) },
)
Expand All @@ -53,6 +53,10 @@ scanner.start(
`PixDotClient` selects a service containing both a writable characteristic
and a notifying or indicating characteristic.

`device.boardSize` is `null` when neither the advertisement nor device name
contains a size. After `READY`, call `requestBoardInfo`; the client updates
`client.boardSize` and `client.device?.boardSize` before `onBoardInfo`.

## Commands

```kotlin
Expand Down
6 changes: 5 additions & 1 deletion android-sdk/README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ val client = PixDotClient(context, object : PixDotClientListener {
scanner.start(
callback = { device ->
scanner.stop()
client.connect(device.bluetoothDevice)
client.connect(device)
},
onError = { error -> handle(error) },
)
Expand All @@ -50,6 +50,10 @@ scanner.start(
`PixDotDeviceScanner` 返回广播名称包含 `PDD_` 的设备。`PixDotClient` 会选择
同时具有可写特征和通知或指示特征的服务。

广播和设备名均不含尺寸时,`device.boardSize` 为 `null`。进入 `READY` 后调用
`requestBoardInfo`;触发 `onBoardInfo` 前,SDK 会更新 `client.boardSize` 和
`client.device?.boardSize`。

## 命令

```kotlin
Expand Down
35 changes: 17 additions & 18 deletions android-sdk/src/main/cpp/pixdot_jni.c
Original file line number Diff line number Diff line change
Expand Up @@ -695,20 +695,15 @@ JNIEXPORT jintArray JNICALL
Java_io_github_oxyroid_pixdot_internal_NativeProtocol_parseAdvertisement(
JNIEnv *env,
jobject receiver,
jbyteArray scan_record,
jint fallback_value) {
pixdot_board_size fallback;
jbyteArray scan_record) {
jbyte *bytes = NULL;
jsize size = 0;
pixdot_advertisement advertisement;
pixdot_board_size detected;
pixdot_status status;
jint values[3];
jintArray result;
(void)receiver;
if (!as_board_size(fallback_value, &fallback)) {
throw_invalid(env, "fallback board size is invalid");
return NULL;
}
if (scan_record != NULL) {
size = (*env)->GetArrayLength(env, scan_record);
bytes = (*env)->GetByteArrayElements(env, scan_record, NULL);
Expand All @@ -719,8 +714,14 @@ Java_io_github_oxyroid_pixdot_internal_NativeProtocol_parseAdvertisement(
status = pixdot_parse_advertisement(
(const uint8_t *)bytes,
(size_t)size,
fallback,
PIXDOT_BOARD_52X52,
&advertisement);
values[2] = pixdot_try_board_size_from_advertisement(
(const uint8_t *)bytes,
(size_t)size,
&detected)
? (jint)detected
: -1;
if (scan_record != NULL) {
(*env)->ReleaseByteArrayElements(
env,
Expand All @@ -734,7 +735,6 @@ Java_io_github_oxyroid_pixdot_internal_NativeProtocol_parseAdvertisement(
}
values[0] = advertisement.cid;
values[1] = advertisement.pid;
values[2] = advertisement.board_size;
result = (*env)->NewIntArray(env, 3);
if (result != NULL) {
(*env)->SetIntArrayRegion(env, result, 0, 3, values);
Expand Down Expand Up @@ -780,23 +780,22 @@ JNIEXPORT jint JNICALL
Java_io_github_oxyroid_pixdot_internal_NativeProtocol_boardSizeFromDeviceName(
JNIEnv *env,
jobject receiver,
jstring name,
jint fallback_value) {
jstring name) {
const char *characters;
pixdot_board_size fallback;
pixdot_board_size result;
bool found;
(void)receiver;
if (name == NULL || !as_board_size(fallback_value, &fallback)) {
throw_invalid(env, "device name arguments are invalid");
return 0;
if (name == NULL) {
throw_invalid(env, "device name must not be null");
return -1;
}
characters = (*env)->GetStringUTFChars(env, name, NULL);
if (characters == NULL) {
return 0;
return -1;
}
result = pixdot_board_size_from_device_name(characters, fallback);
found = pixdot_try_board_size_from_device_name(characters, &result);
(*env)->ReleaseStringUTFChars(env, name, characters);
return (jint)result;
return found ? (jint)result : -1;
}

JNIEXPORT jlong JNICALL
Expand Down
31 changes: 27 additions & 4 deletions android-sdk/src/main/java/io/github/oxyroid/pixdot/PixDotClient.kt
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,12 @@ class PixDotClient(
private var connectionTimeout: Runnable? = null
private var mtuTimeout: Runnable? = null

var device: PixDotDevice? = null
private set

var boardSize: BoardSize? = null
private set

var state: ConnectionState = ConnectionState.DISCONNECTED
private set

Expand Down Expand Up @@ -226,21 +232,34 @@ class PixDotClient(
}
}

@SuppressLint("MissingPermission")
@Synchronized
fun connect(
device: BluetoothDevice,
callback: OperationCallback = NoOpOperationCallback,
) = connect(device, null, callback)

fun connect(
device: PixDotDevice,
callback: OperationCallback = NoOpOperationCallback,
) = connect(device.bluetoothDevice, device, callback)

@SuppressLint("MissingPermission")
@Synchronized
private fun connect(
bluetoothDevice: BluetoothDevice,
pixDotDevice: PixDotDevice?,
callback: OperationCallback,
) {
if (state != ConnectionState.DISCONNECTED) {
callback.onError(PixDotError(ErrorCode.BUSY, "A device is already connected"))
return
}
device = pixDotDevice
boardSize = pixDotDevice?.boardSize
connectCallback = callback
changeState(ConnectionState.CONNECTING)
scheduleConnectionTimeout()
try {
gatt = device.connectGatt(
gatt = bluetoothDevice.connectGatt(
applicationContext,
false,
gattCallback,
Expand Down Expand Up @@ -584,7 +603,11 @@ class PixDotClient(
val copy = value.copyOf()
listener.onNotification(copy)
when (val event = Protocol.parseDeviceEvent(copy)) {
is DeviceEvent.Board -> listener.onBoardInfo(event.info)
is DeviceEvent.Board -> {
boardSize = event.info.boardSize
device?.boardSize = event.info.boardSize
listener.onBoardInfo(event.info)
}
is DeviceEvent.Firmware -> listener.onFirmwareVersion(event.version)
null -> Unit
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,17 @@ class PixDotDeviceScanner(context: Context) : AutoCloseable {
result: ScanResult,
) {
parse(result)?.let { device ->
val previous = seen.put(device.bluetoothDevice.address, device)
if (previous != device) callback.onDevice(device)
val address = device.bluetoothDevice.address
val previous = seen[address]
if (previous == null ||
previous.advertisedName != device.advertisedName ||
previous.cid != device.cid ||
previous.pid != device.pid ||
previous.boardSize != device.boardSize
) {
seen[address] = device
callback.onDevice(device)
}
}
}

Expand Down Expand Up @@ -120,14 +129,15 @@ class PixDotDeviceScanner(context: Context) : AutoCloseable {
val name = result.device.name ?: result.scanRecord?.deviceName ?: return null
if (!Protocol.isSupportedDeviceName(name)) return null
val bytes = result.scanRecord?.bytes
val fallback = Protocol.boardSizeFromDeviceName(name, BoardSize.SIZE_52X52)
val advertisement = Protocol.parseAdvertisement(bytes, fallback)
val advertisement = Protocol.parseAdvertisement(bytes)
val boardSize =
advertisement.boardSize ?: Protocol.boardSizeFromDeviceName(name)
return PixDotDevice(
result.device,
name,
advertisement.cid,
advertisement.pid,
advertisement.boardSize,
boardSize,
)
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,13 +49,16 @@ data class PixelCoordinate(
}
}

data class PixDotDevice(
class PixDotDevice(
val bluetoothDevice: BluetoothDevice,
val advertisedName: String,
val cid: Int,
val pid: Int,
val boardSize: BoardSize,
)
boardSize: BoardSize?,
) {
var boardSize: BoardSize? = boardSize
internal set
}

data class BoardInfo(
val boardSize: BoardSize,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -61,19 +61,13 @@ internal object NativeProtocol {

external fun parseDeviceEvent(data: ByteArray): IntArray

external fun parseAdvertisement(
scanRecord: ByteArray?,
fallbackBoardSize: Int,
): IntArray
external fun parseAdvertisement(scanRecord: ByteArray?): IntArray

external fun boardSideLength(boardSize: Int): Int

external fun isSupportedDeviceName(name: String): Boolean

external fun boardSizeFromDeviceName(
name: String,
fallbackBoardSize: Int,
): Int
external fun boardSizeFromDeviceName(name: String): Int

external fun crc32(data: ByteArray): Long
}
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ internal sealed interface DeviceEvent {
internal data class Advertisement(
val cid: Int,
val pid: Int,
val boardSize: BoardSize,
val boardSize: BoardSize?,
)

internal enum class TransferStep {
Expand Down Expand Up @@ -146,15 +146,14 @@ internal object Protocol {
}
}

fun parseAdvertisement(
scanRecord: ByteArray?,
fallback: BoardSize,
): Advertisement {
val values = NativeProtocol.parseAdvertisement(scanRecord, fallback.ordinal)
fun parseAdvertisement(scanRecord: ByteArray?): Advertisement {
val values = NativeProtocol.parseAdvertisement(scanRecord)
require(values.size == 3) { "Invalid native advertisement result" }
val boardSize = BoardSize.fromNativeValue(values[2])
?: throw IllegalStateException("Native core returned an invalid board size")
return Advertisement(values[0], values[1], boardSize)
return Advertisement(
values[0],
values[1],
BoardSize.fromNativeValue(values[2]),
)
}

fun boardSideLength(boardSize: BoardSize): Int =
Expand All @@ -163,13 +162,8 @@ internal object Protocol {
fun isSupportedDeviceName(name: String): Boolean =
NativeProtocol.isSupportedDeviceName(name)

fun boardSizeFromDeviceName(
name: String,
fallback: BoardSize,
): BoardSize =
BoardSize.fromNativeValue(
NativeProtocol.boardSizeFromDeviceName(name, fallback.ordinal),
) ?: fallback
fun boardSizeFromDeviceName(name: String): BoardSize? =
BoardSize.fromNativeValue(NativeProtocol.boardSizeFromDeviceName(name))

fun crc32(data: ByteArray): Long = NativeProtocol.crc32(data)
}
7 changes: 7 additions & 0 deletions core/include/pixdot/protocol.h
Original file line number Diff line number Diff line change
Expand Up @@ -114,9 +114,16 @@ PIXDOT_API size_t pixdot_frame_payload_capacity(pixdot_board_size board_size);
PIXDOT_API uint32_t pixdot_crc32(const uint8_t *data, size_t size);
PIXDOT_API const char *pixdot_device_name_prefix(void);
PIXDOT_API bool pixdot_is_supported_device_name(const char *name);
PIXDOT_API bool pixdot_try_board_size_from_device_name(
const char *name,
pixdot_board_size *out);
PIXDOT_API pixdot_board_size pixdot_board_size_from_device_name(
const char *name,
pixdot_board_size fallback);
PIXDOT_API bool pixdot_try_board_size_from_advertisement(
const uint8_t *scan_record,
size_t size,
pixdot_board_size *out);

PIXDOT_API pixdot_status pixdot_encode_brightness(
uint8_t percent,
Expand Down
Loading