---@meta

-- Generated from native/src/bindings/core/ble.cpp. Do not edit.

---@class BleObservation
---@field address string
---@field name string
---@field rssi integer
---@field payload string Raw advertisement bytes.
---@field lastSeenMs integer sys.getMillis() at last sighting.

---@class BleFilter
---@field services? string[] Service-data UUIDs to keep.
---@field manufacturers? integer[] Manufacturer ids to keep.

---@class BleLib
ble = {}

---Starts the BLE stack.
---@param name? string Local device name.
---@return true? ok
---@return string? error
function ble.init(name) end

---Stops the BLE stack and releases its memory.
function ble.deinit() end

---Whether the BLE stack is running.
---@return boolean
function ble.isInitialized() end

---Starts passively observing advertisements, coalesced per device.
---@param filter? BleFilter Keep only matching adverts; nil keeps all.
---@return true? ok
---@return string? error
function ble.observe(filter) end

---Stops observing and clears the snapshot.
function ble.unobserve() end

---Whether advertisement observation is running.
---@return boolean
function ble.isObserving() end

---The current snapshot of observed devices.
---@return BleObservation[] devices
function ble.observed() end

---Connects to a peripheral.
---@param address string
---@return true? ok
---@return string? error
function ble.connect(address) end

---Disconnects from the connected peripheral.
function ble.disconnect() end

---Whether a peripheral is connected.
---@return boolean
function ble.isConnected() end

---Reads a characteristic value.
---@param serviceUuid string
---@param characteristicUuid string
---@return string? value
---@return string? error
function ble.read(serviceUuid, characteristicUuid) end

---Writes a characteristic value.
---@param serviceUuid string
---@param characteristicUuid string
---@param value string
---@return true? ok
---@return string? error
function ble.write(serviceUuid, characteristicUuid, value) end

---Starts advertising.
---@param name? string Advertised device name.
---@return true? ok
---@return string? error
function ble.startAdvertising(name) end

---Stops advertising.
function ble.stopAdvertising() end