dglab-bluetooth-protocol: BLE specs for DG-LAB hardware

A reference, not an SDK

The repository is described as sharing the Bluetooth protocols for selected DG-LAB devices, with the stated purpose of giving enthusiasts more freedom to use their devices in creative, flexible and personalised ways. The instruction to readers is short: use the language, framework, or approach of your choice to integrate these devices into your own projects.

That sentence is the whole product. There is no package to install, no service to run, and no sample application to copy. The top level of the repository holds .gitignore, README.md, README_CN.md, a logo image and four directories, one per device family: civet-edging-sensor/, coyote/, opossum-vibrate-controller/ and paw-prints/.

So the deliverable is a specification. If your goal is a working client, the work is yours: implement the BLE transport, the command set and the data formats described in the protocol documents for the device you care about.

This shape has one clear advantage and one clear cost. The advantage is freedom, since nothing forces a particular stack, and a Go, Python, Rust or JavaScript client can all be written from the same documents. The cost is that you inherit the parts of the work a library would have handled, including reconnection behaviour, timing and the ambiguity of a protocol written for one device family and reused for another.

Four device families, four protocol directories

The README indexes the repository by device, and the structure is worth reading carefully because the protocol versions differ per device.

The Coyote Stimulator has three documents: Bluetooth Protocol V2, Bluetooth Protocol V3, and a separate Understanding Pulses page that explains the pulse data shared by those protocol versions. The Pawprint Wireless Button Sensor has Bluetooth Protocol V1.1 plus a second document on external voltage detection with explanation and examples. The Civet Edging Sensor has a single Bluetooth Protocol V1. The Opossum Vibration Controller has a single Bluetooth Protocol V1.

The pattern is that a device that has been through a hardware generation ships more than one protocol version, while a device introduced later has one. A client therefore has to know which generation of hardware it is talking to before it can pick the right document, and that decision is made from the device, not from the repository.

The Understanding Pulses page is a good example of why documentation is the deliverable here. Pulse data is a concept that spans protocol versions, and the repository holds a shared explanation alongside the per-version documents rather than duplicating it, with sample Pulse data for V2 and V3 added in October 2024.

Version numbers follow hardware generations, and get corrected

The protocol versions are labelled V1, V1.1, V2 and V3, and the changelog shows they are not just cosmetic.

In April 2024 parts of the Pulse explanation were updated, and in January 2024 the V3 protocol sections on channel intensity and Pulse output were revised. In April 2025 errors in the V3 Bluetooth protocol documentation were corrected. That last entry matters most for anyone who implemented against V3 before that date, because the corrected document is the authoritative version and an implementation written from the earlier text may not behave the way the current specification describes.

The same pattern shows in the June 2026 entries. The Civet Edging Sensor protocol was added on 2026/06/04, the Opossum Vibration Controller protocol on 2026/06/09, and on 2026/06/11 the Pawprint V1.1 protocol was added along with additional Opossum commands. A protocol document therefore changes both when a new device appears and when an existing one gains commands, and a client that sends a command it learned from an older document may get no response.

For a project integrating these devices, the sensible habit is to treat the protocol version as a dependency to be pinned, and to check the changelog for the specific version you implement rather than reading only the newest document.

The changelog is the maintenance signal

The repository tracks its own history in a dated list at the bottom of the README, and the entries are worth reading as a maintenance record.

The most recent change, on 2026/10/16, added English documentation. The day before, on 2026/10/15, errors in the Civet, Coyote and Pawprint protocol documentation and examples were corrected. On 2026/06/02 the documentation was improved and the repository reorganized, which is the point at which the current per-device directory structure came about.

The English work is a bigger change than it sounds. The README offers a Chinese version, README_CN.md, alongside the English one, and a protocol document that exists only in Chinese is of limited use to a large part of the developer community. The 2026/10/16 entry means the English set is now being maintained in step with the original rather than as a snapshot.

One item is explicitly open. The README says that documentation for V3 accessory interactions and how it will be shared is being revised, which is a clear signal that the V3 documentation is not final, and that an integration written against the current V3 text may need revisiting when the accessory interaction section is rewritten.

The last push to the repository was on 2026-10-16, and there are no GitHub releases, so there is no versioned artefact to pin. You are tracking documents in a branch.

Commercial use needs authorisation the repository does not grant

The licensing position is stated in the README and it is not the usual open source arrangement.

The protocols are published to give enthusiasts more freedom to use their devices, and the README adds that commercial use of this content requires prior authorization. For commercial partnerships there is a contact link to the company, and technical questions about the published protocols and the related development go to a specific contact address, with the README narrowing that channel to questions about the protocols and development only.

The repository itself does not resolve the question. The top level has no LICENSE file, and the licence field for the project is not one GitHub can classify, so there is no stated grant of redistribution rights in the way an MIT or Apache file would provide. The README grants permission for personal and enthusiast projects, and requires authorisation for anything commercial.

That is a legal question rather than a technical one, and this is not advice about it. What matters practically is that a team building a product around one of these devices needs to sort the permission out before the code is written, not after, and that the request goes to a person rather than to a licence file.

What you still have to build

It is worth being concrete about the gap between a protocol document and a working integration, because that gap is the project's entire scope.

Nothing in the repository provides a Bluetooth abstraction, a device pairing helper, a command queue, a state machine for the device's responses, or a reconnection strategy. The only executable artefacts mentioned anywhere are the sample Pulse data added in October 2024, which is a data sample rather than a client.

The alternative approaches are straightforward to describe. A vendor-supplied application for the device hides the protocol entirely but gives you no integration surface. A closed-source third-party library would give you a client at the cost of depending on its maintenance and its licence. Working from the published protocol documents gives you a client you control, with the tradeoff that you own the implementation of everything above the wire format.

Two of the four device families show why that is not trivial. The Civet Edging Sensor and the Opossum Vibration Controller are both still at V1 with no second version published, which means the protocol documents for them are the only description of how those devices behave, including for any command that the hardware accepts but the documentation does not yet cover.

The topic tags on the repository reflect the same spread, listing bluetooth, dg-lab, coyote3, civet-edging-sensor, opossum-vibrate-controller and paw-prints, which is a fair summary of a repository that is four protocol families in one place.

Editorial conclusion

Adopt dglab-bluetooth-protocol if you are building your own client for a DG-LAB Coyote, Pawprint, Civet or Opossum device and are willing to implement the Bluetooth transport yourself from the published protocol descriptions. Skip it if you want a maintained SDK, sample application or a test harness, because the repository contains documentation directories and nothing else, and treat the commercial question as unresolved, since the README requires prior authorisation for commercial use while the repository carries no licence file. Before you start, read the protocol version that matches your hardware generation, check the changelog for corrections to that version, and open a technical question through the contact listed in the README. The last push was on 2026-10-16 and there are no GitHub releases.

Frequently asked questions

Official sources

1. dungeonlab-open/dglab-bluetooth-protocol on GitHub
2. Issues
3. README