Skip to main content

Bluetooth Bring-Up & Usage Guide

Omega4 includes Bluetooth 5.0 (AIC8800D80) with BLE in central and peripheral roles. This page is BLE-only—examples focus on scanning, pairing, GATT, and advertising for sensors and provisioning flows.

Use BLE for:

  • BLE sensor or beacon gateways that forward data over Wi-Fi or Ethernet.
  • Device setup/provisioning flows with a companion mobile app.
  • Low-power accessories like keyboards, barcode scanners, or remote controls.

1. Prerequisites​

  1. Firmware & driver

    • Ensure the kmod-aic8800d-sdio kernel module is built into the image (included since FW v0.0.2).
    • Confirm the controller enumerates as hci0 under /sys/class/bluetooth/.

  2. Networking

    • The steps below download packages from the standard OpenWrt feeds. Make sure the Omega4 has WAN access (or mirror the packages locally).

2. Install User-Space Bluetooth Stack​

opkg update
opkg install \
    bluez-daemon \
    bluez-utils \
    bluez-utils-extra \
    bluez-tools

This pulls in bluetoothd, CLI helpers (bluetoothctl, hciconfig, etc.), and required libraries (dbus, glib2, libreadline, …).

3. Verify the Controller​

  1. List controllers: 
    ls /sys/class/bluetooth
    # Expect: hci0
  2. Inspect capabilities: 
    hciconfig -a
    Confirm Type: Primary Bus: SDIO, UP RUNNING, and matching BD_ADDR.

If the interface shows DOWN, bring it up:

hciconfig hci0 up

4. Start the Bluetooth Daemon​

The init script is shipped as /etc/init.d/bluetoothd.

/etc/init.d/bluetoothd start      # start once
/etc/init.d/bluetoothd enable     # optional: autostart on boot

Verify the daemon:

pgrep -af bluetoothd     # expect /usr/bin/bluetoothd -n

BLE advertising and user-space GATT services require the -E flag on bluetoothd. The init script already starts bluetoothd with -E; keep it running for advertising and custom GATT services.

5. Set the Bluetooth Name​

Align the advertised name with the system hostname so the device shows up consistently in scans.

HOSTNAME=$(uci get system.@system[0].hostname)  # example Omega-1CC0
bluetoothctl system-alias "$HOSTNAME"
bluetoothctl show | grep -i alias               # confirm Alias: Omega-1CC0

Notes:

  • bluetoothctl show will still list Name: BlueZ 5.xx; that field comes from the controller/driver and is not changed by the alias.
  • The alias is what peers see in scans/advertising. It is persisted by bluetoothd. If you change the system hostname later, rerun the bluetoothctl system-alias command to keep them in sync.

6. BLE Central Workflow (Omega4 -> BLE peripheral)​

Scan, pair, and exercise a BLE peripheral using bluetoothctl:

bluetoothctl --timeout 12 scan le         # scan for LE devices only

Then open the shell for GATT operations:

bluetoothctl
[bluetooth]# scan le                      # optional interactive scan
[bluetooth]# pair 90:09:5B:D6:3C:F7       # sample MAC
[bluetooth]# trust 90:09:5B:D6:3C:F7
[bluetooth]# connect 90:09:5B:D6:3C:F7
[bluetooth]# menu gatt
[bluetooth]# list-attributes              # browse services/characteristics
[bluetooth]# select-attribute /org/bluez/hci0/dev_90_09_5B_D6_3C_F7/service0025/char0028
[bluetooth]# read                         # read selected characteristic
[bluetooth]# notify on                    # subscribe if characteristic supports it

Exit menu gatt with back, then quit to leave bluetoothctl. Use disconnect if you want to release the link without closing the shell.

7. BLE Peripheral Workflow (Omega4 advertises)​

With bluetoothd -E already running from init, open bluetoothctl to advertise:

bluetoothctl
[bluetooth]# power on
[bluetooth]# pairable on
[bluetooth]# discoverable on
[bluetooth]# advertise on                 # start connectable advertisement
[bluetooth]# show | grep -E 'Alias|Address'  # sanity check

The advertise on command uses a simple connectable advertisement (sufficient for provisioning and generic BLE client connections). Stop advertising with advertise off. For a custom GATT service (e.g., Wi-Fi setup), follow the Bluetooth GATT Wi-Fi Provisioning guide; the running bluetoothd -E from init is sufficient.

8. Troubleshooting Tips​

SymptomChecks
hciconfig shows DOWNhciconfig hci0 up; inspect `dmesg
bluetoothctl lacks permissionsEnsure bluetoothd is running; restart via /etc/init.d/bluetoothd restart.
No BLE devices found when scanningUse bluetoothctl --timeout 12 scan le; keep the peripheral awake; watch logread -f for SDIO errors.
Advertising command failsMake sure bluetoothd is running with -E; rerun bluetoothctl advertise on.
Notifications never arriveIn menu gatt, select the characteristic and run notify on; ensure the peripheral allows notifications and does not require a CCC write on another handle.
Packages missingRe-run opkg update; confirm the target feed (targets/rockchip/cortexa7) is reachable or mirror the .ipk files.

9. Useful Commands Summary​

# Service control
/etc/init.d/bluetoothd {start|stop|restart|enable|disable}

# Adapter status
hciconfig -a
bluetoothctl show

# Scanning
bluetoothctl --timeout 12 scan le

# Logs
logread -f | grep -i bluetooth
dmesg | grep -i aic_btsdio