This website is available for multi language.

Document

obnizのハードウェアやクラウドの仕様や特徴について


ble.central

use obniz as central

request: scan_start

Related item

path type conditions description
ble.scan.duration integer
  • default 30
 
// Json Example
[
    {
        "ble": {
            "scan": {
                "duration": 30
            }
        }
    }
]

request: scan_stop

path type conditions description
ble.scan null
  • required
 
// Json Example
[
    {
        "ble": {
            "scan": null
        }
    }
]

request: connect

Related item

path type conditions description
ble.connect.address deviceAddress
  • required
 
// Json Example
[
    {
        "ble": {
            "connect": {
                "address": "77e754ab8591"
            }
        }
    }
]

request: disconnect

path type conditions description
ble.disconnect.address deviceAddress
  • required
 
// Json Example
[
    {
        "ble": {
            "disconnect": {
                "address": "77e754ab8591"
            }
        }
    }
]

request: service_get

Related item

path type conditions description
ble.get_services.address deviceAddress
  • required
 
// Json Example
[
    {
        "ble": {
            "get_services": {
                "address": "77e754ab8591"
            }
        }
    }
]

request: characteristic_get

Related item

path type conditions description
ble.get_characteristics.address deviceAddress
  • required
 
ble.get_characteristics.service_uuid uuid
  • required
 
// Json Example
[
    {
        "ble": {
            "get_characteristics": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e"
            }
        }
    }
]

request: characteristic_read

Related item

path type conditions description
ble.read_characteristic.address deviceAddress
  • required
 
ble.read_characteristic.service_uuid uuid
  • required
 
ble.read_characteristic.characteristic_uuid uuid
  • required
 
// Json Example
[
    {
        "ble": {
            "read_characteristic": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179"
            }
        }
    }
]

request: characteristic_write

Related item

path type conditions description
ble.write_characteristic.address deviceAddress
  • required
 
ble.write_characteristic.service_uuid uuid
  • required
 
ble.write_characteristic.characteristic_uuid uuid
  • required
 
ble.write_characteristic.data dataArray
  • required
 
ble.write_characteristic.needResponse boolean
  • default true
 
// Json Example
[
    {
        "ble": {
            "write_characteristic": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "data": [16, 34, 242],
                "needResponse": true
            }
        }
    }
]

request: characteristic_register_notify

Related item

path type conditions description
ble.register_notify_characteristic.address deviceAddress
  • required
 
ble.register_notify_characteristic.service_uuid uuid
  • required
 
ble.register_notify_characteristic.characteristic_uuid uuid
  • required
 
// Json Example
[
    {
        "ble": {
            "register_notify_characteristic": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179"
            }
        }
    }
]

request: characteristic_unregister_notify

Related item

path type conditions description
ble.unregister_notify_characteristic.address deviceAddress
  • required
 
ble.unregister_notify_characteristic.service_uuid uuid
  • required
 
ble.unregister_notify_characteristic.characteristic_uuid uuid
  • required
 
// Json Example
[
    {
        "ble": {
            "unregister_notify_characteristic": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179"
            }
        }
    }
]

request: descriptor_get

Related item

path type conditions description
ble.get_descriptors.address deviceAddress
  • required
 
ble.get_descriptors.service_uuid uuid
  • required
 
ble.get_descriptors.characteristic_uuid uuid
  • required
 
// Json Example
[
    {
        "ble": {
            "get_descriptors": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179"
            }
        }
    }
]

request: descriptor_read

Related item

path type conditions description
ble.read_descriptor.address deviceAddress
  • required
 
ble.read_descriptor.service_uuid uuid
  • required
 
ble.read_descriptor.characteristic_uuid uuid
  • required
 
ble.read_descriptor.descriptor_uuid uuid
  • required
 
// Json Example
[
    {
        "ble": {
            "read_descriptor": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "descriptor_uuid": "d822b53c"
            }
        }
    }
]

request: descriptor_write

Related item

path type conditions description
ble.write_descriptor.address deviceAddress
  • required
 
ble.write_descriptor.service_uuid uuid
  • required
 
ble.write_descriptor.characteristic_uuid uuid
  • required
 
ble.write_descriptor.descriptor_uuid uuid
  • required
 
ble.write_descriptor.data dataArray
  • required
 
ble.write_descriptor.needResponse boolean
  • default true
 
// Json Example
[
    {
        "ble": {
            "write_descriptor": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "descriptor_uuid": "d822b53c",
                "data": [16, 34, 242],
                "needResponse": true
            }
        }
    }
]

response: scan

path type conditions description
ble.scan_result.address deviceAddress
  • required
 
ble.scan_result.ble_event_type string
  • required
  • enum
    • "connectable_advertisemnt"
    • "connectable_directed_advertisemnt"
    • "scannable_advertising"
    • "non_connectable_advertising"
    • "scan_response"
 
ble.scan_result.device_type string
  • required
  • enum
    • "ble"
    • "dumo"
    • "breder"
 
ble.scan_result.address_type string
  • required
  • enum
    • "public"
    • "random"
    • "rpa_public"
    • "rpa_random"
 
ble.scan_result.flag integer
  • required
  • 0 ≤ value
 
ble.scan_result.rssi integer
  • required
  • value ≤ 0
 
ble.scan_result.adv_data bleAdvertiseData    
ble.scan_result.scan_resp bleAdvertiseData    
//Response Example
[
    {
        "ble": {
            "scan_result": {
                "address": "77e754ab8591",
                "ble_event_type": "connectable_advertisemnt",
                "device_type": "ble",
                "address_type": "public",
                "flag": 500,
                "rssi": 500,
                "adv_data": [2, 1, 26, 7, 9, 83, 97, 109, 112, 108, 101],
                "scan_resp": [7, 9, 83, 97, 109, 112, 108, 101]
            }
        }
    }
]

response: scan_finish

path type conditions description
ble.scan_result_finish boolean
  • required
  • const true
 
//Response Example
[
    {
        "ble": {
            "scan_result_finish": true
        }
    }
]

response: status_update

path type conditions description
ble.status_update.address deviceAddress
  • required
 
ble.status_update.status string
  • required
  • enum
    • "connected"
    • "disconnected"
 
//Response Example
[
    {
        "ble": {
            "status_update": {
                "address": "77e754ab8591",
                "status": "connected"
            }
        }
    }
]

response: service_get

path type conditions description
ble.get_service_result.address deviceAddress
  • required
 
ble.get_service_result.service_uuid uuid
  • required
 
//Response Example
[
    {
        "ble": {
            "get_service_result": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e"
            }
        }
    }
]

response: service_get_finish

path type conditions description
ble.get_service_result_finish.address deviceAddress
  • required
 
//Response Example
[
    {
        "ble": {
            "get_service_result_finish": {
                "address": "77e754ab8591"
            }
        }
    }
]

response: characteristic_get

path type conditions description
ble.get_characteristic_result.address deviceAddress
  • required
 
ble.get_characteristic_result.service_uuid uuid
  • required
 
ble.get_characteristic_result.characteristic_uuid uuid
  • required
 
ble.get_characteristic_result.properties[] string
  • enum
    • "broadcast"
    • "read"
    • "write_without_response"
    • "write"
    • "notify"
    • "indicate"
    • "auth"
    • "extended_properties"
 
//Response Example
[
    {
        "ble": {
            "get_characteristic_result": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "properties": [
                    "broadcast"
                ]
            }
        }
    }
]

response: characteristic_get_finish

path type conditions description
ble.get_characteristic_result_finish.address deviceAddress
  • required
 
ble.get_characteristic_result_finish.service_uuid uuid
  • required
 
//Response Example
[
    {
        "ble": {
            "get_characteristic_result_finish": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e"
            }
        }
    }
]

response: characteristic_write

path type conditions description
ble.write_characteristic_result.address deviceAddress
  • required
 
ble.write_characteristic_result.service_uuid uuid
  • required
 
ble.write_characteristic_result.characteristic_uuid uuid
  • required
 
ble.write_characteristic_result.result string
  • required
  • enum
    • "success"
    • "failed"
 
//Response Example
[
    {
        "ble": {
            "write_characteristic_result": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "result": "success"
            }
        }
    }
]

response: characteristic_read

path type conditions description
ble.read_characteristic_result.address deviceAddress
  • required
 
ble.read_characteristic_result.service_uuid uuid
  • required
 
ble.read_characteristic_result.characteristic_uuid uuid
  • required
 
ble.read_characteristic_result.result string
  • required
  • enum
    • "success"
    • "failed"
 
ble.read_characteristic_result.data dataArray
  • required
 
//Response Example
[
    {
        "ble": {
            "read_characteristic_result": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "result": "success",
                "data": [16, 34, 242]
            }
        }
    }
]

response: characteristic_register_notify

Related item

path type conditions description
ble.characteristic_register_notify_result.address deviceAddress
  • required
 
ble.characteristic_register_notify_result.service_uuid uuid
  • required
 
ble.characteristic_register_notify_result.characteristic_uuid uuid
  • required
 
ble.characteristic_register_notify_result.result boolean
  • required
 
//Response Example
[
    {
        "ble": {
            "characteristic_register_notify_result": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "result": true
            }
        }
    }
]

response: characteristic_notify

path type conditions description
ble.nofity_characteristic.address deviceAddress
  • required
 
ble.nofity_characteristic.service_uuid uuid
  • required
 
ble.nofity_characteristic.characteristic_uuid uuid
  • required
 
ble.nofity_characteristic.data dataArray
  • required
 
//Response Example
[
    {
        "ble": {
            "nofity_characteristic": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "data": [16, 34, 242]
            }
        }
    }
]

response: characteristic_notify

path type conditions description
ble.nofity_characteristic.address deviceAddress
  • required
 
ble.nofity_characteristic.service_uuid uuid
  • required
 
ble.nofity_characteristic.characteristic_uuid uuid
  • required
 
ble.nofity_characteristic.data dataArray
  • required
 
//Response Example
[
    {
        "ble": {
            "nofity_characteristic": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "data": [16, 34, 242]
            }
        }
    }
]

response: descriptor_get

path type conditions description
ble.get_descriptor_result.address deviceAddress
  • required
 
ble.get_descriptor_result.service_uuid uuid
  • required
 
ble.get_descriptor_result.characteristic_uuid uuid
  • required
 
ble.get_descriptor_result.descriptor_uuid uuid
  • required
 
//Response Example
[
    {
        "ble": {
            "get_descriptor_result": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "descriptor_uuid": "d822b53c"
            }
        }
    }
]

response: descriptor_get_finish

path type conditions description
ble.get_descriptor_result_finish.address deviceAddress
  • required
 
ble.get_descriptor_result_finish.service_uuid uuid
  • required
 
ble.get_descriptor_result_finish.characteristic_uuid uuid
  • required
 
//Response Example
[
    {
        "ble": {
            "get_descriptor_result_finish": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179"
            }
        }
    }
]

response: descriptor_write

path type conditions description
ble.write_descriptor_results.address deviceAddress
  • required
 
ble.write_descriptor_results.service_uuid uuid
  • required
 
ble.write_descriptor_results.characteristic_uuid uuid
  • required
 
ble.write_descriptor_results.descriptor_uuid uuid
  • required
 
ble.write_descriptor_results.result string
  • required
  • enum
    • "success"
    • "failed"
 
//Response Example
[
    {
        "ble": {
            "write_descriptor_results": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "descriptor_uuid": "d822b53c",
                "result": "success"
            }
        }
    }
]

response: descriptor_read

path type conditions description
ble.read_descriptor_results.address deviceAddress
  • required
 
ble.read_descriptor_results.service_uuid uuid
  • required
 
ble.read_descriptor_results.characteristic_uuid uuid
  • required
 
ble.read_descriptor_results.descriptor_uuid uuid
  • required
 
ble.read_descriptor_results.result string
  • required
  • enum
    • "success"
    • "failed"
 
ble.read_descriptor_results.data dataArray
  • required
 
//Response Example
[
    {
        "ble": {
            "read_descriptor_results": {
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "descriptor_uuid": "d822b53c",
                "result": "success",
                "data": [16, 34, 242]
            }
        }
    }
]

response: error

path type conditions description
ble.error.error_code integer
  • required
 
ble.error.module_error_code integer    
ble.error.function_code integer    
ble.error.message string
  • required
 
ble.error.address deviceAddress    
ble.error.service_uuid uuidOrNull    
ble.error.characteristic_uuid uuidOrNull    
ble.error.descriptor_uuid uuidOrNull    
//Response Example
[
    {
        "ble": {
            "error": {
                "error_code": 0,
                "module_error_code": 0,
                "function_code": 0,
                "message": "ERROR MESSAGE",
                "address": "77e754ab8591",
                "service_uuid": "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e",
                "characteristic_uuid": "8d3591bda71140fd8f9f00535fe57179",
                "descriptor_uuid": "d822b53c"
            }
        }
    }
]

type defines

bleAdvertiseData

type conditions examples description
array
  • length ≤ 31
  • items
    • 0 ≤ value ≤ 255
  • [2, 1, 26, 7, 9, 83, 97, 109, 112, 108, 101]
  • [7, 9, 83, 97, 109, 112, 108, 101]
 

dataArray

type conditions examples description
array
  • items
    • 0 ≤ value ≤ 255
  • [16, 34, 242]
  • [100, 255, 21, 0, 21]
Binary data array. 

deviceAddress

type conditions examples description
string
  • length = 12
  • "77e754ab8591"
Bluetooth device id. It's hexString cannot contain '0x' or '-'. 

uuid

type conditions examples description
string
  • 4 ≤ length ≤ 36
  • "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e"
  • "8d3591bda71140fd8f9f00535fe57179"
  • "d822b53c"
  • "de44"
Bluetooth uuid. If it contain '-', it ignored. 

uuidOrNull

type conditions examples description
string,null
  • 4 ≤ length ≤ 36
  • "e1cfb0d1-ae63-4d6f-b3b6-de2054f87e5e"
  • "8d3591bda71140fd8f9f00535fe57179"
  • "d822b53c"
  • "de44"
  • null
Bluetooth uuid. If it contain '-', it ignored.