obniz
Version:
obniz sdk for javascript
665 lines (466 loc) • 20.9 kB
Markdown
# <a name="ble-peripheral">ble.peripheral</a>
use obniz as peripheral
## request: <a name="-request-ble-peripheral-advertisement_start">advertisement_start</a>
Related item
- [/response/ble/peripheral/status](#-response-ble-peripheral-status)
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.advertisement.adv_data` | [bleAdvertiseData](#bleadvertisedata) | <ul><li>required</li></ul> | |
| `ble.advertisement.scan_resp` | [bleAdvertiseData](#bleadvertisedata) | | |
```
// Json Example
[
{
"ble": {
"advertisement": {
"adv_data": [2, 1, 26, 7, 9, 83, 97, 109, 112, 108, 101],
"scan_resp": [7, 9, 83, 97, 109, 112, 108, 101]
}
}
}
]
```
## request: <a name="-request-ble-peripheral-advertisement_stop">advertisement_stop</a>
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.advertisement` | null | <ul><li>required</li></ul> | |
```
// Json Example
[
{
"ble": {
"advertisement": null
}
}
]
```
## request: <a name="-request-ble-peripheral-service_start">service_start</a>
callback of external device connected
Related item
- [/response/ble/peripheral/status](#-response-ble-peripheral-status)
- [/response/ble/peripheral/characteristic_notify_read](#-response-ble-peripheral-characteristic_notify_read)
- [/response/ble/peripheral/characteristic_notify_write](#-response-ble-peripheral-characteristic_notify_write)
- [/response/ble/peripheral/descriptor_notify_read](#-response-ble-peripheral-descriptor_notify_read)
- [/response/ble/peripheral/descriptor_notify_write](#-response-ble-peripheral-descriptor_notify_write)
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.services[].uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.services[].characteristics[].uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.services[].characteristics[].data` | [dataArray](#dataarray) | | |
| `ble.peripheral.services[].characteristics[].properties[]` | string | <ul><li>enum <ul><li>`"broadcast"`</li><li>`"read"`</li><li>`"write_without_response"`</li><li>`"write"`</li><li>`"notify"`</li><li>`"indicate"`</li><li>`"auth"`</li><li>`"extended_properties"`</li></ul></li></ul> | |
| `ble.peripheral.services[].characteristics[].permissions[]` | string | <ul><li>default `read,write`</li><li>enum <ul><li>`"read"`</li><li>`"read_encrypted"`</li><li>`"read_encrypted_mitm"`</li><li>`"write"`</li><li>`"write_encrypted"`</li><li>`"write_encrypted_mitm"`</li><li>`"write_signed"`</li><li>`"write_signed_mitm"`</li></ul></li></ul> | |
| `ble.peripheral.services[].characteristics[].descriptors[].uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.services[].characteristics[].descriptors[].data` | [dataArray](#dataarray) | | |
| `ble.peripheral.services[].characteristics[].descriptors[].permissions[]` | string | <ul><li>default `read,write`</li><li>enum <ul><li>`"read"`</li><li>`"read_encrypted"`</li><li>`"read_encrypted_mitm"`</li><li>`"write"`</li><li>`"write_encrypted"`</li><li>`"write_encrypted_mitm"`</li><li>`"write_signed"`</li><li>`"write_signed_mitm"`</li></ul></li></ul> | |
```
// Json Example
[
{
"ble": {
"peripheral": {
"services": [
{
"uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristics": [
{
"uuid": "8d3591bda71140fd8f9f00535fe57179",
"data": [16, 34, 242],
"properties": [
"broadcast"
],
"permissions": [
[
"read",
"write"
]
],
"descriptors": [
{
"uuid": "d822b53c",
"data": [100, 255, 21, 0, 21],
"permissions": [
[
"read",
"write"
]
]
}
]
}
]
}
]
}
}
}
]
```
## request: <a name="-request-ble-peripheral-service_stop">service_stop</a>
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.stop_service.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
```
// Json Example
[
{
"ble": {
"peripheral": {
"stop_service": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e"
}
}
}
}
]
```
## request: <a name="-request-ble-peripheral-service_stop_all">service_stop_all</a>
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral` | null | <ul><li>required</li></ul> | |
```
// Json Example
[
{
"ble": {
"peripheral": null
}
}
]
```
## request: <a name="-request-ble-peripheral-characteristic_read">characteristic_read</a>
read characteristic on own service
Related item
- [/response/ble/peripheral/characteristic_read](#-response-ble-peripheral-characteristic_read)
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.read_characteristic.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_characteristic.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
```
// Json Example
[
{
"ble": {
"peripheral": {
"read_characteristic": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179"
}
}
}
}
]
```
## request: <a name="-request-ble-peripheral-characteristic_write">characteristic_write</a>
write characteristic on own service
Related item
- [/response/ble/peripheral/characteristic_write](#-response-ble-peripheral-characteristic_write)
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.write_characteristic.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_characteristic.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_characteristic.data` | [dataArray](#dataarray) | <ul><li>required</li></ul> | |
```
// Json Example
[
{
"ble": {
"peripheral": {
"write_characteristic": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"data": [16, 34, 242]
}
}
}
}
]
```
## request: <a name="-request-ble-peripheral-descriptor_read">descriptor_read</a>
read descriptor on own service
Related item
- [/response/ble/peripheral/descriptor_read](#-response-ble-peripheral-descriptor_read)
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.read_descriptor.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_descriptor.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_descriptor.descriptor_uuid` | [uuid](#uuid) | | |
```
// Json Example
[
{
"ble": {
"peripheral": {
"read_descriptor": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"descriptor_uuid": "d822b53c"
}
}
}
}
]
```
## request: <a name="-request-ble-peripheral-descriptor_write">descriptor_write</a>
write descriptor on own service
Related item
- [/response/ble/peripheral/descriptor_write](#-response-ble-peripheral-descriptor_write)
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.write_descriptor.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_descriptor.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_descriptor.descriptor_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_descriptor.data` | [dataArray](#dataarray) | <ul><li>required</li></ul> | |
```
// Json Example
[
{
"ble": {
"peripheral": {
"write_descriptor": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"descriptor_uuid": "d822b53c",
"data": [16, 34, 242]
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-status">status</a>
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.connection_status.address` | [deviceAddress](#deviceaddress) | <ul><li>required</li></ul> | |
| `ble.peripheral.connection_status.status` | string | <ul><li>required</li><li>enum <ul><li>`"connected"`</li><li>`"disconnected"`</li></ul></li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"connection_status": {
"address": "77e754ab8591",
"status": "connected"
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-characteristic_read">characteristic_read</a>
callback of read characteristic
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.read_characteristic_result.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_characteristic_result.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_characteristic_result.data` | [dataArray](#dataarray) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_characteristic_result.result` | string | <ul><li>required</li><li>enum <ul><li>`"success"`</li><li>`"failed"`</li></ul></li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"read_characteristic_result": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"data": [16, 34, 242],
"result": "success"
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-characteristic_write">characteristic_write</a>
callback of write characteristic
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.write_characteristic_result.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_characteristic_result.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_characteristic_result.result` | string | <ul><li>required</li><li>enum <ul><li>`"success"`</li><li>`"failed"`</li></ul></li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"write_characteristic_result": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"result": "success"
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-characteristic_notify_read">characteristic_notify_read</a>
callback of external device read characteristic
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.notify_read_characteristic.address` | [deviceAddress](#deviceaddress) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_read_characteristic.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_read_characteristic.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"notify_read_characteristic": {
"address": "77e754ab8591",
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179"
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-characteristic_notify_write">characteristic_notify_write</a>
callback of external device write characteristic
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.notify_write_characteristic.address` | [deviceAddress](#deviceaddress) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_write_characteristic.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_write_characteristic.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_write_characteristic.data` | [dataArray](#dataarray) | <ul><li>required</li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"notify_write_characteristic": {
"address": "77e754ab8591",
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"data": [16, 34, 242]
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-descriptor_read">descriptor_read</a>
callback of read descriptor
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.read_descriptor_result.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_descriptor_result.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_descriptor_result.descriptor_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_descriptor_result.data` | [dataArray](#dataarray) | <ul><li>required</li></ul> | |
| `ble.peripheral.read_descriptor_result.result` | string | <ul><li>required</li><li>enum <ul><li>`"success"`</li><li>`"failed"`</li></ul></li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"read_descriptor_result": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"descriptor_uuid": "d822b53c",
"data": [16, 34, 242],
"result": "success"
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-descriptor_write">descriptor_write</a>
callback of write descriptor
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.write_descriptor_result.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_descriptor_result.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_descriptor_result.descriptor_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.write_descriptor_result.result` | string | <ul><li>required</li><li>enum <ul><li>`"success"`</li><li>`"failed"`</li></ul></li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"write_descriptor_result": {
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"descriptor_uuid": "d822b53c",
"result": "success"
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-descriptor_notify_read">descriptor_notify_read</a>
callback of external device read descriptor
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.notify_read_descriptor.address` | [deviceAddress](#deviceaddress) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_read_descriptor.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_read_descriptor.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_read_descriptor.descriptor_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"notify_read_descriptor": {
"address": "77e754ab8591",
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"descriptor_uuid": "d822b53c"
}
}
}
}
]
```
## response: <a name="-response-ble-peripheral-descriptor_notify_write">descriptor_notify_write</a>
callback of external device write descriptor
| path | type | conditions | description |
|:---- |:---- |:---- |:---- |
| `ble.peripheral.notify_write_descriptor.address` | [deviceAddress](#deviceaddress) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_write_descriptor.service_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_write_descriptor.characteristic_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_write_descriptor.descriptor_uuid` | [uuid](#uuid) | <ul><li>required</li></ul> | |
| `ble.peripheral.notify_write_descriptor.data` | [dataArray](#dataarray) | <ul><li>required</li></ul> | |
```
//Response Example
[
{
"ble": {
"peripheral": {
"notify_write_descriptor": {
"address": "77e754ab8591",
"service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
"characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
"descriptor_uuid": "d822b53c",
"data": [16, 34, 242]
}
}
}
}
]
```
# type defines
## <a name="bleadvertisedata">bleAdvertiseData</a>
| type | conditions | examples | description |
|:----|:----|:----|:----|
| array | <ul><li>length ≤ 31</li><li>items<br/><ul><li>0 ≤ value ≤ 255</li></ul></li></ul> | <ul><li>`[2, 1, 26, 7, 9, 83, 97, 109, 112, 108, 101]`</li><li>`[7, 9, 83, 97, 109, 112, 108, 101]`</li></ul> | |
## <a name="dataarray">dataArray</a>
| type | conditions | examples | description |
|:----|:----|:----|:----|
| array | <ul><li>items<br/><ul><li>0 ≤ value ≤ 255</li></ul></li></ul> | <ul><li>`[16, 34, 242]`</li><li>`[100, 255, 21, 0, 21]`</li></ul> | Binary data array. |
## <a name="deviceaddress">deviceAddress</a>
| type | conditions | examples | description |
|:----|:----|:----|:----|
| string | <ul><li>length = 12</li></ul> | <ul><li>`"77e754ab8591"`</li></ul> | Bluetooth device id. It's hexString cannot contain '0x' or '-'. |
## <a name="uuid">uuid</a>
| type | conditions | examples | description |
|:----|:----|:----|:----|
| string | <ul><li>4 ≤ length ≤ 36</li></ul> | <ul><li>`"e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e"`</li><li>`"8d3591bda71140fd8f9f00535fe57179"`</li><li>`"d822b53c"`</li><li>`"de44"`</li></ul> | Bluetooth uuid. If it contain '-', it ignored. |