Audiens: Pengembang aplikasi seluler, pemimpin firmware tertanam, dan pemilik SDK sisi merek yang harus mengintegrasikan skema BLE GATT pena baca ke dalam aplikasi host mereka, dan yang perlu memahami karakteristik mana yang merupakan UUID 16-bit yang diadopsi SIG (siap interoperabilitas) versus UUID 128-bit yang ditentukan vendor (propietar), serta bagaimana skema tersebut berkembang antara revisi firmware tanpa merusak aplikasi yang sudah ada di lapangan.
Setiap pena baca yang dikirim dari kedua pabrik kami sejak 2023 mengiklankan tanda tangan layanan BLE yang sama: UUID layanan Human Interface Device 16-bit yang diadopsi SIG sebesar 0x1812, ditambah UUID layanan 128-bit yang ditentukan vendor yang digunakan aplikasi host untuk mengidentifikasi pena sebagai perangkat bermerek Smart Reading Pen. Di dalam layanan tersebut terdapat 11 karakteristik, di mana 6 diadopsi SIG dan 5 ditentukan vendor. Total basis data GATT menempati 1,8 KB ROM pada firmware Q6/Q8 3.3.1 dan 1,4 KB pada firmware F8 3.1.2.
Artikel ini membahas setiap UUID dalam skema, menjelaskan mengapa masing-masing diadopsi SIG atau ditentukan vendor, dan mendokumentasikan aturan yang kami ikuti saat memperluas skema untuk pelanggan OEM baru agar 230+ aplikasi distributor yang sudah ada tidak rusak.
1. Mengapa Skema GATT Penting
Periferal BLE tanpa skema GATT yang terdokumentasi adalah kotak hitam. Aplikasi host harus menebak karakteristik mana yang berfungsi untuk apa. Di industri elektronik konsumen, inilah penyebab tiket nomor satu "aplikasi tidak dapat menemukan pena". Dari 47.000+ unit yang telah kami kirim, tiket terkait skema telah turun dari 4,2% dari seluruh tiket pada 2023 menjadi 0,7% pada 2026, sebagian besar karena kami kini mengirimkan skema yang dibekukan dengan ekstensi yang memiliki versi.
Skema yang kami gunakan pada firmware Q6/Q8 3.3.1 adalah Skema GATT v3.0, terakhir direvisi 2025-11. Skema v2.x sebelumnya dikirimkan pada firmware K7/KF1 1.9.5. Aplikasi yang ditulis untuk v2.x tetap berfungsi pada v3.0 karena kami hanya menambah karakteristik, tidak pernah menghapusnya, dan tidak pernah mengubah UUID karakteristik.
2. Tata Letak Layanan Tingkat Atas
Pena mengiklankan tiga layanan dalam daftar layanan utamanya:
| Layanan | UUID | Jenis | Wajib |
|---|---|---|---|
| Generic Access | 0x1800 | SIG 16-bit | Ya |
| Generic Attribute | 0x1801 | SIG 16-bit | Ya |
| Human Interface Device | 0x1812 | SIG 16-bit | Ya |
| Layanan Vendor Smart Reading Pen | 8E0C0001-7B3C-4F8E-9F4D-2C8B5A1E0001 | Vendor 128-bit | Ya |
| Layanan Baterai | 0x180F | SIG 16-bit | Ya |
| Informasi Perangkat | 0x180A | SIG 16-bit | Ya |
Generic Access (0x1800) dan Generic Attribute (0x1801) bersifat wajib pada setiap periferal BLE. Keduanya mengekspos nama perangkat, appearance, dan indikasi perubahan layanan. Human Interface Device (0x1812) adalah layanan HOGP yang membawa laporan ketukan OID. Vendor Service adalah tempat karakteristik proprietary kami berada. Battery (0x180F) dan Device Information (0x180A) adalah layanan standar yang diadopsi SIG dan diharapkan ada di setiap platform host.
Pulpen mengiklankan daftar layanan primer lengkap dalam satu paket AD ketika MTU memungkinkan. Pada F8 (BLE 5.1, MTU 247) kami menyertakan semua enam layanan. Pada radio K7/KF1 yang lebih lama (MTU 23) kami hanya menyertakan dua layanan dalam paket AD dan sisanya ditemukan oleh host melalui service discovery.
3. Karakteristik Layanan HID (0x1812)
Layanan HID mengekspos enam karakteristik:
| Karakteristik | UUID | Properti | Catatan |
|---|---|---|---|
| HID Information | 0x2A4A | Read | bcdHID, bCountryCode, flags |
| Report Map | 0x2A4B | Read | Blob deskriptor dari TC-058 |
| Protocol Mode | 0x2A4E | Read, Write | Report vs Boot |
| HID Control Point | 0x2A4C | WriteWithoutResponse | Suspend / Resume |
| Report (Reference 1) | 0x2A4D | Notify, Write, WriteWithoutResponse | Laporan ketukan OID |
| Report (Reference 2) | 0x2A4D | Notify | Audio VU meter |
UUID tunggal 0x2A4D digunakan ulang untuk dua laporan karena layanan HID mengizinkan beberapa karakteristik Report yang diidentifikasi melalui deskriptor Report Reference. Pada Q6/Q8 kami menggunakan dua karakteristik Report: yang pertama adalah laporan ketukan OID yang dijelaskan di TC-058, yang kedua adalah audio VU meter (digunakan oleh aplikasi host untuk menampilkan indikator VU kecil saat TTS diputar).
4. Karakteristik Layanan Vendor
UUID layanan vendor adalah 8E0C0001-7B3C-4F8E-9F4D-2C8B5A1E0001. UUID 128-bit ini dihasilkan menggunakan SHA-1 atas nama perusahaan kami dan sebuah prefiks tetap. Di dalam layanan vendor terdapat lima karakteristik:
| Karakteristik | UUID | Properti | Tujuan |
|---|---|---|---|
| Brand ID | 8E0C0002-7B3C-4F8E-9F4D-2C8B5A1E0001 | Read | Identifier merek 4-byte yang dibekukan |
| Dictionary Status | 8E0C0003-7B3C-4F8E-9F4D-2C8B5A1E0001 | Read, Notify | Paket bahasa yang sedang dimuat |
| Audio Control | 8E0C0004-7B3C-4F8E-9F4D-2C8B5A1E0001 | Write | Volume, mute, preset EQ |
| Telemetri | 8E0C0005-7B3C-4F8E-9F4D-2C8B5A1E0001 | Notify, Indicate | Log, kode error |
| Kontrol OTA | 8E0C0006-7B3C-4F8E-9F4D-2C8B5A1E0001 | Write, Indicate | Pemicu pembaruan firmware |
Setiap karakteristik mengikuti konvensi SIG: UUID 128-bit dengan prefiks umum (8E0C0000-7B3C-4F8E-9F4D-2C8B5A1E0000) dan ID instance 16-bit. 4 byte terakhir dari ID instance mengodekan nomor karakteristik. Hal ini membuat UUID mudah dipindai secara visual di aplikasi pemindai BLE.
5. Layanan Baterai (0x180F)
Layanan baterai mengekspos satu karakteristik:
| Karakteristik | UUID | Properti | Tujuan |
|---|---|---|---|
| Level Baterai | 0x2A19 | Read, Notify | 0–100% daya |
Pen mengumumkan level baterai pada 1 Hz di firmware Q6/Q8 3.3.1. Sampel ADC dirata-ratakan selama 4 sampel untuk menghilangkan noise. Perubahan lebih dari 5% memicu notifikasi segera; delta yang lebih kecil dikemas ke dalam notifikasi periodik 1 Hz. Aplikasi host juga dapat melakukan pembacaan manual.
Sebuah poin halus: nilai karakteristik baterai dalam persen, bukan milivolt, sesuai spesifikasi SIG. Pembacaan milivolt diekspos melalui karakteristik vendor terpisah 8E0C0010-7B3C-4F8E-9F4D-2C8B5A1E0001 untuk diagnostik teknis.
6. Layanan Device Information (0x180A)
Layanan Device Information mengekspos:
| Karakteristik | UUID | Properti | Nilai pada Q6/Q8 |
|---|---|---|---|
| Manufacturer Name | 0x2A29 | Read | "Smart Reading Pen Mfg Co." |
| Nomor Model | 0x2A24 | Baca | "Q8" |
| Nomor Seri | 0x2A25 | Baca | ASCII 12 karakter per unit |
| Revisi Perangkat Keras | 0x2A26 | Baca | "Rev. D" |
| Revisi Firmware | 0x2A26 | Baca | "3.3.1" |
| Revisi Perangkat Lunak | 0x2A28 | Baca | "Build 8642" |
| ID Sistem | 0x2A23 | Baca | OUI + UUID acak per unit |
Karakteristik Model Number digunakan oleh aplikasi host untuk memuat skin UI yang tepat. Kami tidak menempatkan PII di sini (tidak ada alamat MAC di System ID; System ID adalah OUI perusahaan ditambah UUID acak per unit).
7. Prosedur Discovery yang Harus Diikuti Aplikasi Host
Aplikasi host yang berperilaku baik mengikuti urutan berikut:
- Pindai paket iklan yang berisi 0x1812 dalam daftar UUID layanan.
- Hubungkan dengan interval koneksi 15 ms, slave latency 0 ms, supervision timeout 4 d.
- Minta pertukaran MTU; terima hingga 247.
- Temukan semua layanan primer.
- Untuk setiap layanan, temukan semua karakteristik.
- Untuk setiap karakteristik, baca descriptor Characteristic Presentation Format.
- Berlangganan notifikasi pada 0x2A4D (ketukan OID) dan 8E0C0005 (telemetri).
- Baca Battery Level (0x2A19) dan Device Information.
Aplikasi yang berperilaku buruk terhubung dengan parameter default dan langsung mencoba menulis. Kami melihat hal ini pada 14% aplikasi host pihak pertama. Hasilnya, koneksi butuh ~3 d untuk stabil, bukan ~300 md. Penilaian QA kami menghargai aplikasi yang mengikuti prosedur ini.
8. Kebijakan Ekstensi Skema
Kami memperluas skema GATT mengikuti tiga aturan:
- Jangan pernah menghapus karakteristik. Setelah UUID dikirim dalam firmware produksi, UUID tersebut tetap ada di skema selama masa pakai platform. Aplikasi lama tetap membacanya dan mengabaikan nilainya.
- Jangan pernah mengubah UUID. UUID adalah identitas 128-bit. Mengubahnya akan merusak setiap aplikasi yang mencatatnya.
- Tambahkan karakteristik baru pada ID instans berikutnya yang kosong. Layanan vendor memiliki 256 ID instans yang dicadangkan (0x0001 hingga 0x0100). Ketika kami menambahkan karakteristik baru, kami memilih yang berikutnya yang kosong dan menaikkan versi minor skema.
Skema v3.0 (saat ini) menggunakan ID instans 0x0001 hingga 0x0010. Skema v4.0 (direncanakan untuk firmware L5 4.3.0) akan menggunakan ID instans 0x0011 hingga 0x0020 untuk karakteristik baru terkait telemetri mode kelas.
9. Performa: Waktu Discovery
| Langkah | Waktu pada Q6/Q8 | Waktu pada F8 | Waktu pada K7/KF1 |
|---|---|---|---|
| Hubungkan ke layanan pertama | 95 md | 110 md | 145 md |
| Semua layanan ditemukan | 280 md | 330 md | 520 md |
| Semua karakteristik ditemukan | 410 ms | 490 ms | 880 ms |
| Deskriptor CCCD dibaca | 220 ms | 280 ms | 480 ms |
| Pertukaran MTU | 38 ms | 42 ms | 65 ms |
| Total pasangan pertama | 1,04 s | 1,25 s | 2,1 s |
Aplikasi host yang menyelesaikan semua ini di bawah 1 s dianggap "cepat"; 1,5 s dianggap "normal"; lebih dari 2 s dianggap "buruk". Seluruh 38 aplikasi referensi internal kami untuk iOS/Android/Windows berada di bawah 1,5 s.
10. Perbedaan Skema Antar Model
| Karakteristik | Q6/Q8 | F8 | K7/KF1 | L5 | T2/Y6 | P2 |
|---|---|---|---|---|---|---|
| HID 0x2A4D (OID) | Ya | Ya | Ya | Ya | Ya | Ya |
| HID 0x2A4D (VU) | Ya | Tidak | Tidak | Ya | Ya | Tidak |
| Baterai 0x2A19 | Ya | Ya | Ya | Ya | Ya | Ya |
| Brand ID 8E0C0002 | Ya | Ya | Ya | Ya | Ya | Ya |
| Status Kamus 8E0C0003 | Ya | Ya | Ya | Ya | Ya | Ya |
| Kontrol Audio 8E0C0004 | Yes | No | No | Yes | Yes | No |
| Telemetri 8E0C0005 | Yes | Yes | Yes | Yes | Yes | Yes |
| Kontrol OTA 8E0C0006 | Yes | Yes | Yes | Yes | Yes | Yes |
| Audio Vendor VU 8E0C0007 | Yes | No | No | Yes | Yes | No |
| Mode Tes Vendor 8E0C0008 | Yes | Yes | No | Yes | Yes | No |
| Mode Kelas Vendor 8E0C0009 | No | No | No | Yes | Yes | No |
[perbaiki: kontaminasi han — gunakan hanya aksara asli Bahasa Indonesia; hilangkan setiap karakter dengan aksara asing] Model L5, T2, dan Y6 adalah satu-satunya model yang memiliki fitur mode kelas, karena model-model tersebut dijual untuk saluran pendidikan. K7/KF1 adalah pena pembaca untuk pengguna tunggal di rumah, sehingga fitur kelas tidak tersedia.
11. Perbedaan Skema Antar Revisi Firmware
| Firmware | Versi Skema | Tambah | Hapus | Kompatibel Dengan |
|---|---|---|---|---|
| K7 1.9.0 | 2.0 | — | — | Skema 2.0 |
| K7 1.9.5 | 2.1 | 8E0C0006 OTA | — | Skema 2.0, 2.1 |
| F8 3.1.0 | 2.5 | 8E0C0007 VU | — | Skema 2.5 |
| F8 3.1.2 | 2.5.1 | — | — | Schema 2.5 |
| Q6/Q8 3.3.0 | 3.0 | 8E0C0008 Test | — | Schema 3.0 |
| Q6/Q8 3.3.1 | 3.0 | — | — | Schema 3.0 |
| L5 4.2.0 | 3.1 | 8E0C0009 Classroom | — | Schema 3.1 |
| T2/Y6 2.6.4 | 3.1 | — | — | Schema 3.1 |
Skema ini kompatibel secara maju: aplikasi yang dibuat untuk Schema 2.0 dapat terhubung ke pena yang menjalankan firmware Schema 3.1 dan membaca semua karakteristik Schema 2.0; aplikasi tersebut hanya akan melewati karakteristik baru.
12. Cara Mengalokasikan UUID Spesifik Merek
Pelanggan ODM dapat meminta karakteristik spesifik merek. Kami mengalokasikan dari rentang 0x0100 hingga 0x01FF. Pelanggan memilih 16 ID instance dari rentang ini, dan kami mendaftarkannya dalam manifes skema GATT. Manifes tersebut adalah berkas YAML di repositori firmware; manifes mencantumkan semua ID instance, nama karakteristik, mask properti, ukuran, dan nilai awal. CI akan gagal jika dua pelanggan meminta ID instance yang sama.
Manifes untuk firmware Q6/Q8 3.3.1 mencantumkan 38 rentang spesifik merek yang saat ini dialokasikan. Kami dapat menampung 13 lagi sebelum kehabisan ruang 0x0100 hingga 0x01FF dan perlu memperluas ke 0x0200.
13. Trik Kompresi Database GATT
Database GATT dapat diratakan menjadi blob 1,8 KB di ROM. Format yang kami gunakan:
[uint16 service_count]
untuk setiap service:
[uint16 service_uuid_type] [128-bit UUID]
[uint16 characteristic_count]
untuk setiap characteristic:
[uint16 char_uuid_type] [128-bit UUID]
[uint8 properties]
[uint8 value_size]
[uint8 descriptor_count]
untuk setiap descriptor:
[uint16 desc_uuid_type] [128-bit UUID]
[uint8 payload_size] [payload]
Blob dihasilkan pada waktu build firmware oleh skrip Python yang membaca manifes YAML. Total biaya ROM adalah 1.824 byte pada firmware Q6/Q8 3.3.1. F8 menghemat 384 byte dengan menggabungkan service HID menjadi 5 karakteristik alih-alih 6 (tanpa Audio VU).
14. Suite Validasi yang Kami Jalankan pada Setiap Skema
| Pemeriksaan | Alat | Kriteria Lulus |
|---|---|---|
| Keunikan UUID | Skrip CI Python | Tidak ada UUID duplikat dalam manifes |
| Kompatibilitas maju skema | Harness Python kustom | Schema N+1 dapat diurai sebagai Schema N |
| Waktu discovery | Saleae + Wireshark | Di bawah 1,5 dtk pada Q6/Q8 |
| Laju notifikasi baterai | Logic analyzer | Tepat 1 Hz ±5% |
| Karakteristik OTA | Skrip CI | Karakteristik OTA hadir pada semua firmware produksi |
Sebuah skema yang gagal dalam pemeriksaan mana pun akan ditolak. Dari 86 rilis firmware sejak 2023, 4 ditolak pada gerbang ini.
16. Bacaan Terkait
- Reading Pen USB HID dan HID over GATT
- Reading Pen HID Report Descriptor dan Usage Page
- Reading Pen Bluetooth Pairing SSP Secure Simple Pairing
- Reading Pen GATT Server dan Notification Mechanism
- Reading Pen Bluetooth 5.0 vs 5.2 vs 5.3
- Reading Pen OTA Firmware Update Mechanism
- Reading Pen Telemetry Sample Rate
- Reading Pen Cryptography dan TrustZone