# pnote_flutter_sdk (lite)
English | [简体中文](./README.md)
BLE Flutter plugin for the Shengyun voice recorder pen — **lite edition**. Pure Dart implementation on top of `flutter_blue_plus`, no native SDK required.
## Features
| Capability | Description |
|------|------|
| Scan / connect | Filters by service `0xAE20`; reconnect by name + address (`connectDeviceAndAddress`) |
| Device info | Time sync / battery / storage / firmware version / MAC |
| Recording control | Start / stop / pause / resume / state query; mirrors physical-key and device-side pause/resume events |
| Realtime audio stream | Raw opus frames pushed automatically while recording (`recordDataStream`), for live transcription / monitoring |
| File management | List / download (resumable, byte-range) / delete one / delete all |
| AppJson compatibility layer | Emits JSON events identical to the iOS SDK (`getCBCAppJson()` etc., ×11) |
## Getting started
### 1. Add the dependency
```yaml
dependencies:
pnote_flutter_sdk:
git:
url: https://github.com/SonicloudTech/sonicloud_opensdk.git
path: pnote-flutter-sdk
```
### 2. Configure permissions
**Android** `AndroidManifest.xml`:
```xml
```
**iOS** `Info.plist`:
```xml
NSBluetoothAlwaysUsageDescription
Required to connect to the voice recorder pen
```
Runtime permissions must be requested by your app (the example app relies on the system prompt; `permission_handler` is recommended for production apps).
### 3. Usage
```dart
final sdk = AudioPenSdk();
// Scan (filtered by 0xAE20)
sdk.startSearch().listen((results) {
// results: List (flutter_blue_plus type)
});
// Connect
final device = await sdk.connectDevice(results.first.device);
// Basic info
await device.syncTime();
final battery = await device.getCBC(); // BatteryInfo
final capacity = await device.getDeviceCapacity();
final version = await device.getDeviceVersion();
// Recording
await device.startRecord();
await device.stopRecord();
// Files
final files = await device.getRecordFileList(); // List
await device.startGetFile(files.first.name); // streamed via fileDataStream
await device.delAllFileData();
// Disconnect
await device.closeConnect();
```
## API reference
### AudioPenSdk — scanning & connection entry point
| Method / property | Returns | Description |
|------|------|------|
| `AudioPenSdk({debugLog = true})` | — | Entry point; `debugLog` toggles scan/GATT/raw-byte logging |
| `isBluetoothOn` | `Future` | Whether Bluetooth is supported and turned on |
| `adapterState` | `Stream` | Adapter state stream (on/off/turning on/…) |
| `startSearch({timeout = 15s})` | `Stream>` | Scan filtered by service `0xAE20`; emits **cumulative** result lists, stops automatically on timeout. `ScanResult` is a flutter_blue_plus type |
| `scanAll({timeout = 15s})` | `Stream>` | Unfiltered scan of all nearby BLE devices (for debugging "cannot find device") |
| `stopSearch()` | `Future` | Stop scanning |
| `connectDevice(device)` | `Future` | Connect to a `ScanResult.device`, returns a device session |
| `connectDeviceAndAddress(name, address)` | `Future` | Reconnect by name + address: matches the current scan cache first, then falls back to connecting by address directly (works even if the device is not advertising — ideal for last-session reconnect) |
### AudioPenDevice · connection & state
| Method / property | Returns | Description |
|------|------|------|
| `name` | `String` | Device name |
| `id` | `String` | Device ID (the MAC address) |
| `isDeviceConnected` | `bool` | Whether currently connected |
| `connectionState` | `Stream` | Connection state stream: `disconnected` / `connecting` / `connected` |
| `closeConnect()` | `Future` | Disconnect and release all resources |
| `debugLog` (get/set), `setShowLog(bool)` | — | Runtime switch for raw-byte/GATT logging |
### Device info
| Method | Returns | Description |
|------|------|------|
| `syncTime([time])` | `Future` | Sync time to the device (defaults to now) |
| `getCBC()` | `Future` | Battery: `percent` (0–100), `charging` |
| `getDeviceCapacity()` | `Future` | Storage: `freeKb` / `totalKb` / `usedKb` (KB) |
| `getDeviceVersion()` | `Future` | Firmware version string (e.g. `"1.2.23"`) |
| `getSn()` | `Future` | SN — the protocol has no SN command, MAC is returned instead |
### Recording control
| Method | Returns | Description |
|------|------|------|
| `startRecord()` | `Future` | Start recording; the device then pushes the realtime opus stream automatically (see `recordDataStream`) |
| `stopRecord()` | `Future` | Stop and save; the command is **sent twice** to guarantee delivery, and the audio-stream gate is closed |
| `pauseRecord()` / `continueRecord()` | `Future` | Pause / resume recording |
| `getRecordState()` | `Future` | Query recording state: `idle` / `recording` / `paused` / `unknown` |
### File management
| Method | Returns | Description |
|------|------|------|
| `getRecordFileList()` | `Future>` | File list; multi-frame replies are accumulated automatically. `PenFile`: `name`, `sizeBytes`, `durationSec`, `isCall` (call recording) |
| `startGetFile(name, {offset = 0})` | `Future` | Download a whole file; pass bytes already received as `offset` to resume |
| `startGetFileByFromToEnd(name, {offset, end})` | `Future` | Download the byte range `[offset, end)` |
| `stopGetFile([fileName])` | `Future` | Abort the current download (`fileName` kept only for iOS-parity, optional) |
| `delFileData(name)` | `Future` | Delete one file, returns success |
| `delAllFileData()` | `Future` | Delete all files, returns success |
`FileDownloadResult`: `endCode` (`completed` / `notFound` / `offsetTooLarge` / `other`), `fileName` (name echoed by the device), `receivedBytes`, `success`.
### Streams
| Stream | Type | Description |
|------|------|------|
| `statusStream` | `Stream` | Device mode state (1-byte bitmask): `recording` / `playing` / `usbMode` / `realtimeAsr` / `importing` / `playPaused` / `busy` |
| `keyEventStream` | `Stream` | Physical key events: cmd `1` start / `3` save / `5` pause / `7` resume. Per the protocol, on receiving 1/3 the app should send the corresponding record command back (see the example app) |
| `deviceRecordStream` | `Stream` | Device-side physical pause/resume/stop: `0` stop / `2` pause / `3` resume |
| `recordDataStream` | `Stream` | Realtime recording opus raw bytes (40 B/frame = 20 ms @16 kbps; trailing partial frames are dropped); produced only while recording |
| `fileDataStream` | `Stream` | Every file chunk pushed by the device during a download |
| `downloadProgressStream` | `Stream` | Download progress (cumulative bytes received) |
| `appEventStream` | `Stream` | Unified app JSON event stream (key/mode/device-side events merged; format below) |
| `debugLogStream` | `Stream` | Low-level debug log lines (when `debugLog` is on) |
| `rawFrameStream` | `Stream` | All successfully parsed raw frames (debugging) |
### AppJson compatibility layer (×11)
Emits JSON events byte-for-byte identical to the iOS SDK, so apps migrating from the native SDK switch **without code changes**. Unified format:
```json
{"cmd":"","state":"0","data":{ ... }}
```
(All values inside `data` are serialized as strings, matching the iOS SDK.)
| Method | cmd | Event |
|------|------|------|
| `getCBCAppJson()` | 6 | Battery: `{"cbc":"95"}` |
| `getSnAppJson()` | 7 | SN / MAC |
| `startRecordAppJson()` / `stopRecordAppJson()` / `pauseRecordAppJson()` / `continueRecordAppJson()` | 3 | Recording control results (`record_state`: `1` recording / `0` stopped / `2` paused) |
| `getRecordFileListAppJson()` | 4 | File list (with duration/size) |
| `getDeviceCapacityAppJson()` | 13 | Storage |
| `delAllFileDataAppJson()` | 14 | Delete-all result (`delete_state`: `0` ok / `1` failed) |
| `getRecordStateAppJson()` | 9 | Recording state query result |
| `getDeviceVersionAppJson()` | 17 | Firmware version |
### Protocol cmd cheat sheet
The frame body is `dataType(1B) | cmd(1B) | params`; frames carry a `0x5A` magic header + CRC-16/XMODEM (little-endian length). Every device data frame must be ACKed with the same sequence number (`dataType=3`, no cmd) — **handled automatically by the SDK**. Direction: `↓` app→device, `↑` device→app.
**Control channel (dataType = 0)**
| cmd | Dir | Meaning | Body / reply format |
|----|----|------|------|
| 0 | ↓ | Sync time | 7 B: year(2 B LE)/month/day/hour/min/sec |
| 1 / 2 | ↓ / ↑ | Get storage / reply | Reply 8 B: free(4 B) + total(4 B), KB, little-endian |
| 3 / 4 | ↓ / ↑ | Get battery / reply | Reply 1 B: `0–100` level; `110` = charging |
| 10 / 11 | ↓ / ↑ | Get firmware version / reply | Reply string, e.g. `"1.2.23"` |
| 12 / 13 | ↓ / ↑ | Get MAC / reply | Reply string (colon-separated, may carry an `s` prefix) |
| 14 | ↑ | Device mode state (unsolicited) | 1 B bitmask: bit0 playing / bit1 recording / bit2 USB / bit3 realtime ASR / bit4 importing / bit5 play-paused / bit6 busy |
| 18 | ↓ | App foreground/background | 1 B: `1` foreground / `2` background |
**Audio channel (dataType = 1 — recording control & realtime stream)**
| cmd | Dir | Meaning | Body |
|----|----|------|------|
| 0x00 | ↓ | Start recording | `01 00` (device then pushes opus frames automatically) |
| 0x01 | ↑ | Realtime opus audio frame | 40 B/frame (20 ms @16 kbps, mono); passed through as `recordDataStream` |
| 0x02 | ↓ | Stop (save) recording | `01 02`, sent twice to guarantee delivery; device stops streaming |
| 0x03 | ↓ | Pause / resume | `01 03 01` pause / `01 03 00` resume |
| 0x04 | ↑ | Device-side physical pause/resume/stop | 1 B flag: `2` stop / `1` pause / `0` resume (mapped to 0/2/3 on `deviceRecordStream`) |
**File channel (dataType = 2)**
| cmd | Dir | Meaning | Body / reply |
|----|----|------|------|
| 0 / 1 / 18 | ↓ / ↑ / ↑ | Get file list / list frames (**multi-frame**) / list done | Each frame: count/records; the SDK accumulates until cmd=18. Record layout: duration(4 B BE) + size(4 B BE) + name (variable length, `.`-terminated) |
| 2 | ↓ | Download file (resumable) | offset(4 B LE) + name; pass bytes received so far to resume |
| 12 | ↓ | Range download | offset(4 B LE) + end(4 B LE) + name, fetches `[offset, end)` |
| 3 / 4 | ↑ / ↑ | File start / file data chunk | cmd 3 echoes the current file name; cmd 4 is file bytes (`fileDataStream`) |
| 5 | ↑ | Current file end | 1 B end code: `0` completed / `1` not found / `2` offset too large / `3` other stop |
| 6 | ↑ | All files end | — |
| 7 | ↓ | Abort download | Device stops streaming |
| 8 / 13 | ↓ / ↑ | Delete file(s) / result | Request: 4 B padding + name; reply 1 B: `0` ok / `1` failed |
| 9 / 10 | ↓ / ↑ | Delete all / result | Reply 1 B: `0` ok / `1` failed |
**Key channel (dataType = 3 — same value as ACK: no cmd means an ACK frame)**
| cmd | Dir | Meaning | Notes |
|----|----|------|------|
| 1 | ↑ | User pressed the physical "start" key | Odd cmds are device notifications; on 1/3 the app should reply with the matching record command (iOS parity) |
| 3 | ↑ | User pressed the physical "save" key | Same as above |
| 5 / 7 | ↑ | Physical "pause" / "resume" key | Same as above |
| 2 / 4 / 6 / 8 | ↓ | App-initiated start/save/pause/resume | Device replies with the **same cmd**, 1 B: `1` ok / `2` failed |
| 19 / 20 | ↓ / ↑ | Query recording state / reply | Reply 1 B: `1` recording / `2` idle |
For the full frame layout (magic/length/CRC byte order), calibration notes and on-device test records, see [ARCHITECTURE.md](ARCHITECTURE.md) (Chinese).
## Notes
- **BLE requires a real device**: emulators have no Bluetooth; scan results will always be empty.
- Debug switches: `AudioPenSdk(debugLog: true)` prints scan/GATT/raw-byte logs (`[BLE-SCAN]` prefixes); after connecting, turn it off with `device.debugLog = false`; `sdk.scanAll()` scans unfiltered to troubleshoot advertising issues.
- The protocol layer (frame codec / CRC / reply parsing) has no Bluetooth dependency and is unit-testable offline (`flutter test`, 51 cases).
## License
MIT — see [LICENSE](LICENSE).