---
title: "Bluetooth: iOS clients"
canonical_url: https://developer.repebble.com/pebbleos/docs/samples/subsys/bluetooth/ios_clients/
last_updated: 2026-11-21
sdk_version: 4.44
---
# Bluetooth: iOS clients

Source: https://developer.repebble.com/pebbleos/docs/samples/subsys/bluetooth/ios_clients/

This sample is a peripheral that shows the notifications of an iOS device with the ANCS client (`pbl/bluetooth/clients/ancs.h`) and what it plays with the AMS client (`pbl/bluetooth/clients/ams.h`), on NimBLE alone.

It advertises a solicitation for the Apple Notification Center Service, so that iOS lists it among the accessories to pair with. Once a device connects, the sample asks it to secure the link, since the services are only there for a paired accessory, and then starts the clients: each looks for its service and subscribes to it when the device has it.

Each client is in a file of its own, and the sample has an option for each: `CONFIG_SAMPLE_ANCS` and `CONFIG_SAMPLE_AMS`, both on by default. With only the second, the sample solicits the Apple Media Service instead.

## Notifications

The ANCS client subscribes to the Data Source and the Notification Source, in that order so that no response is missed. Each notification the device adds, modifies or removes is printed as the client reports it. For the first two the sample then asks the client for the title and the message, and prints them once the client has the whole response. The client runs one request at a time, so the attributes of a notification that comes while another is being asked about are not got.

## Media

The AMS client subscribes to the Remote Command, which tells the commands the media player takes, and to the Entity Update, with which it then registers for the playback info and the volume of the player, and for the artist, the album, the title and the duration of the track. Their values are printed as the device tells them: once registered, and whenever they change. A value that did not fit comes cut, and the sample then reads the whole of it.

## Bluetooth

The sample handles the GAP events of its connection itself, and so hands the notifications it receives to the listeners with `pbl_bt_gattc_notify_rx()`, which is how the clients get them. The clients call back on the NimBLE host thread.

The bond is kept by NimBLE’s config store in a settings file: the board overlays give each board a filesystem partition.

Run:

`pbl samples samples/subsys/bluetooth/ios_clients`

Boards:

every board

### Sources

src/main.c

```
#include "sample.h"#include \<stdint.h\>#include \<stdio.h\>#include \<string.h\>#include \<pbl/bluetooth/ams.h\>#include \<pbl/bluetooth/ancs.h\>#include \<pbl/bluetooth/clients/gatt.h\>#include \<pbl/fs/fs.h\>#include \<pbl/fs/pfs.h\>#include \<pbl/kernel/sem.h\>#include \<pbl/kernel/types.h\>#include \<pbl/util/size.h\>#include \<host/ble\_hs.h\>#include \<host/util/util.h\>#include \<nimble/nimble\_port.h\>#include \<nimble/nimble\_port\_pebble.h\>#include \<services/gap/ble\_svc\_gap.h\>#include \<services/gatt/ble\_svc\_gatt.h\>#define NAME "PebbleOS"static struct pbl\_fs\_mount s\_mount = {.mnt\_point = "/", .ops = &pbl\_fs\_pfs\_ops};static PBL\_SEM\_DEFINE(s\_synced, 0, 1);static uint8\_t s\_own\_addr\_type;/\* iOS lists the accessories that ask for ANCS; the payload has room for one service. \*/#if defined(CONFIG\_SAMPLE\_ANCS)#define SOLICITED\_UUID PBL\_BT\_ANCS\_UUID\_SERVICE#else#define SOLICITED\_UUID PBL\_BT\_AMS\_UUID\_SERVICE#endifstatic int prv\_gap\_event(struct ble\_gap\_event \*event, void \*arg);static void prv\_advertise(void) {/\* \* Flags, and a solicitation for a service of the device. The payload is built by hand, as \* NimBLE's advertising fields have no solicitation: each field is its length (type and \* data), its type and its data. \*/static const uint8\_t data[] = {1 + 1,BLE\_HS\_ADV\_TYPE\_FLAGS,BLE\_HS\_ADV\_F\_DISC\_GEN | BLE\_HS\_ADV\_F\_BREDR\_UNSUP,1 + 16, BLE\_HS\_ADV\_TYPE\_SOL\_UUIDS128, SOLICITED\_UUID,};const struct ble\_hs\_adv\_fields rsp\_fields = {.name = (const uint8\_t \*)NAME,.name\_len = strlen(NAME),.name\_is\_complete = 1,};const struct ble\_gap\_adv\_params params = {.conn\_mode = BLE\_GAP\_CONN\_MODE\_UND,.disc\_mode = BLE\_GAP\_DISC\_MODE\_GEN,};int rc;rc = ble\_gap\_adv\_set\_data(data, sizeof(data));if (rc == 0) {rc = ble\_gap\_adv\_rsp\_set\_fields(&rsp\_fields);}if (rc == 0) {rc = ble\_gap\_adv\_start(s\_own\_addr\_type, nullptr, BLE\_HS\_FOREVER, &params, prv\_gap\_event,nullptr);}if (rc != 0) {printf("ios\_clients: advertising failed (%d)\n", rc);return;}printf("ios\_clients: advertising as %s\n", NAME);}/\* Runs on the host thread. \*/static int prv\_gap\_event(struct ble\_gap\_event \*event, void \*arg) {struct ble\_gap\_conn\_desc desc;switch (event-\>type) {case BLE\_GAP\_EVENT\_CONNECT:if (event-\>connect.status != 0) {prv\_advertise();break;}printf("ios\_clients: connected\n");/\* The services are only there for a paired accessory, over an encrypted link. \*/(void)ble\_gap\_security\_initiate(event-\>connect.conn\_handle);break;case BLE\_GAP\_EVENT\_DISCONNECT:printf("ios\_clients: disconnected, reason 0x%03x\n", event-\>disconnect.reason);#if defined(CONFIG\_SAMPLE\_ANCS)sample\_ancs\_stop();#endif#if defined(CONFIG\_SAMPLE\_AMS)sample\_ams\_stop();#endifprv\_advertise();break;case BLE\_GAP\_EVENT\_ENC\_CHANGE:if (event-\>enc\_change.status != 0) {printf("ios\_clients: encryption failed (%d)\n", event-\>enc\_change.status);break;}#if defined(CONFIG\_SAMPLE\_ANCS)sample\_ancs\_start(event-\>enc\_change.conn\_handle);#endif#if defined(CONFIG\_SAMPLE\_AMS)sample\_ams\_start(event-\>enc\_change.conn\_handle);#endifbreak;case BLE\_GAP\_EVENT\_NOTIFY\_RX:(void)pbl\_bt\_gattc\_notify\_rx(event-\>notify\_rx.conn\_handle, event-\>notify\_rx.attr\_handle,event-\>notify\_rx.om);break;case BLE\_GAP\_EVENT\_REPEAT\_PAIRING:/\* A bonded peer that lost its keys: forget ours, and pair again. \*/if (ble\_gap\_conn\_find(event-\>repeat\_pairing.conn\_handle, &desc) == 0) {(void)ble\_store\_util\_delete\_peer(&desc.peer\_id\_addr);}return BLE\_GAP\_REPEAT\_PAIRING\_RETRY;default:break;}return 0;}static void prv\_on\_sync(void) {pbl\_sem\_give(&s\_synced);}int main(void) {int rc;/\* The store keeps the bond in a settings file. \*/rc = pbl\_fs\_mount(&s\_mount);if (rc != 0) {printf("ios\_clients: mount failed (%d)\n", rc);return rc;}nimble\_port\_init();ble\_hs\_cfg.sync\_cb = prv\_on\_sync;ble\_hs\_cfg.store\_status\_cb = ble\_store\_util\_status\_rr;ble\_store\_config\_init();ble\_svc\_gap\_init();ble\_svc\_gatt\_init();rc = ble\_svc\_gap\_device\_name\_set(NAME);if (rc != 0) {printf("ios\_clients: setting the name failed (%d)\n", rc);return rc;}nimble\_port\_pebble\_init();pbl\_sem\_take(&s\_synced, PBL\_FOREVER);rc = ble\_hs\_util\_ensure\_addr(0);if (rc == 0) {rc = ble\_hs\_id\_infer\_auto(0, &s\_own\_addr\_type);}if (rc != 0) {printf("ios\_clients: no address (%d)\n", rc);return rc;}prv\_advertise();return 0;}
```

src/ancs.c

```
#include "sample.h"#include \<stdint.h\>#include \<stdio.h\>#include \<pbl/bluetooth/clients/ancs.h\>#include \<pbl/util/size.h\>#define TITLE\_MAX 32#define MESSAGE\_MAX 96static const struct pbl\_bt\_ancs\_attr\_req s\_attrs[] = {{.id = PBL\_BT\_ANCS\_NOTIF\_ATTR\_TITLE, .max\_len = TITLE\_MAX},{.id = PBL\_BT\_ANCS\_NOTIF\_ATTR\_MESSAGE, .max\_len = MESSAGE\_MAX},};/\* Room for the response: its header, and each attribute with its own. \*/PBL\_BT\_ANCS\_CLIENT\_DEFINE(s\_client,5 + 2 \* sizeof(struct pbl\_bt\_ancs\_attr) + TITLE\_MAX + MESSAGE\_MAX);static void prv\_discovered(struct pbl\_bt\_ancs\_client \*client, int status) {if (status != 0) {printf("ancs: not on the peer (%d)\n", status);return;}printf("ancs: found\n");/\* The Data Source first, so that no response is missed. \*/(void)pbl\_bt\_ancs\_client\_subscribe(client, PBL\_BT\_ANCS\_SOURCE\_DATA, true);(void)pbl\_bt\_ancs\_client\_subscribe(client, PBL\_BT\_ANCS\_SOURCE\_NOTIFICATION, true);}static void prv\_subscribed(struct pbl\_bt\_ancs\_client \*client, enum pbl\_bt\_ancs\_source source,bool enable, int status) {if (status != 0) {printf("ancs: subscribing failed (%d)\n", status);} else if (source == PBL\_BT\_ANCS\_SOURCE\_NOTIFICATION) {printf("ancs: subscribed\n");}}static void prv\_notification(struct pbl\_bt\_ancs\_client \*client,const struct pbl\_bt\_ancs\_notif \*notif) {static const char \*const events[] = {"added", "modified", "removed"};if (notif-\>event \>= PBL\_ARRAY\_SIZE(events)) {return;}printf("ancs: notification %u %s, category %u%s\n", (unsigned int)notif-\>uid,events[notif-\>event], notif-\>category,(notif-\>flags & PBL\_BT\_ANCS\_FLAG\_PRE\_EXISTING) ? ", from before" : "");/\* One request at a time: the attributes of a notification that comes meanwhile are not got. \*/if (notif-\>event != PBL\_BT\_ANCS\_EVENT\_REMOVED) {(void)pbl\_bt\_ancs\_client\_get\_notif\_attrs(client, notif-\>uid, s\_attrs, PBL\_ARRAY\_SIZE(s\_attrs));}}static void prv\_notif\_attrs(struct pbl\_bt\_ancs\_client \*client, int status, uint32\_t uid,const struct pbl\_bt\_ancs\_attr \*const \*attrs, uint8\_t num\_attrs) {static const char \*const names[] = {"title", "message"};if (status != 0) {/\* E.g. the notification is gone since. \*/printf("ancs: request refused (%d)\n", status);return;}for (uint8\_t i = 0; i \< num\_attrs; i++) {printf("ancs: %s: %.\*s\n", names[i], (int)attrs[i]-\>len, (const char \*)attrs[i]-\>value);}}static const struct pbl\_bt\_ancs\_client\_cb s\_cb = {.discovered = prv\_discovered,.subscribed = prv\_subscribed,.notification = prv\_notification,.notif\_attrs = prv\_notif\_attrs,};void sample\_ancs\_start(uint16\_t conn\_handle) {const int rc = pbl\_bt\_ancs\_client\_start(&s\_client, conn\_handle, &s\_cb);if (rc != 0) {printf("ancs: starting the client failed (%d)\n", rc);}}void sample\_ancs\_stop(void) {pbl\_bt\_ancs\_client\_stop(&s\_client);}
```

src/ams.c

```
#include "sample.h"#include \<stdint.h\>#include \<stdio.h\>#include \<pbl/bluetooth/clients/ams.h\>#include \<pbl/util/size.h\>PBL\_BT\_AMS\_CLIENT\_DEFINE(s\_client);static const uint8\_t s\_player\_attrs[] = {PBL\_BT\_AMS\_PLAYER\_ATTR\_PLAYBACK\_INFO,PBL\_BT\_AMS\_PLAYER\_ATTR\_VOLUME,};static const uint8\_t s\_track\_attrs[] = {PBL\_BT\_AMS\_TRACK\_ATTR\_ARTIST,PBL\_BT\_AMS\_TRACK\_ATTR\_ALBUM,PBL\_BT\_AMS\_TRACK\_ATTR\_TITLE,PBL\_BT\_AMS\_TRACK\_ATTR\_DURATION,};static const char \*prv\_attr\_name(uint8\_t entity, uint8\_t attr) {static const char \*const player[] = {"player", "playback", "volume"};static const char \*const track[] = {"artist", "album", "title", "duration"};if (entity == PBL\_BT\_AMS\_ENTITY\_PLAYER && attr \< PBL\_ARRAY\_SIZE(player)) {return player[attr];} else if (entity == PBL\_BT\_AMS\_ENTITY\_TRACK && attr \< PBL\_ARRAY\_SIZE(track)) {return track[attr];}return "?";}static void prv\_discovered(struct pbl\_bt\_ams\_client \*client, int status) {if (status != 0) {printf("ams: not on the peer (%d)\n", status);return;}printf("ams: found\n");(void)pbl\_bt\_ams\_client\_subscribe(client, PBL\_BT\_AMS\_SOURCE\_REMOTE\_COMMAND, true);(void)pbl\_bt\_ams\_client\_subscribe(client, PBL\_BT\_AMS\_SOURCE\_ENTITY\_UPDATE, true);}static void prv\_subscribed(struct pbl\_bt\_ams\_client \*client, enum pbl\_bt\_ams\_source source,bool enable, int status) {if (status != 0) {printf("ams: subscribing failed (%d)\n", status);return;}/\* The Entity Update only takes registrations once subscribed to. \*/if (source == PBL\_BT\_AMS\_SOURCE\_ENTITY\_UPDATE) {printf("ams: subscribed\n");(void)pbl\_bt\_ams\_client\_register(client, PBL\_BT\_AMS\_ENTITY\_PLAYER, s\_player\_attrs,PBL\_ARRAY\_SIZE(s\_player\_attrs));(void)pbl\_bt\_ams\_client\_register(client, PBL\_BT\_AMS\_ENTITY\_TRACK, s\_track\_attrs,PBL\_ARRAY\_SIZE(s\_track\_attrs));}}static void prv\_commands(struct pbl\_bt\_ams\_client \*client, const uint8\_t \*commands,uint8\_t num\_commands) {printf("ams: the player takes commands");for (uint8\_t i = 0; i \< num\_commands; i++) {printf(" %u", commands[i]);}printf("\n");}static void prv\_update(struct pbl\_bt\_ams\_client \*client, const struct pbl\_bt\_ams\_update \*update) {/\* One read at a time: a value cut while another is being read stays cut. \*/if ((update-\>flags & PBL\_BT\_AMS\_FLAG\_TRUNCATED) &&pbl\_bt\_ams\_client\_read\_attr(client, update-\>entity, update-\>attr) == 0) {return;}printf("ams: %s: %.\*s\n", prv\_attr\_name(update-\>entity, update-\>attr), (int)update-\>len,(const char \*)update-\>value);}static void prv\_registered(struct pbl\_bt\_ams\_client \*client, int status) {if (status != 0) {printf("ams: registering failed (%d)\n", status);}}static void prv\_attr\_read(struct pbl\_bt\_ams\_client \*client, int status,enum pbl\_bt\_ams\_entity entity, uint8\_t attr, const uint8\_t \*value,uint16\_t len) {if (status != 0) {printf("ams: reading failed (%d)\n", status);return;}printf("ams: %s: %.\*s\n", prv\_attr\_name(entity, attr), (int)len, (const char \*)value);}static const struct pbl\_bt\_ams\_client\_cb s\_cb = {.discovered = prv\_discovered,.subscribed = prv\_subscribed,.commands = prv\_commands,.update = prv\_update,.registered = prv\_registered,.attr\_read = prv\_attr\_read,};void sample\_ams\_start(uint16\_t conn\_handle) {const int rc = pbl\_bt\_ams\_client\_start(&s\_client, conn\_handle, &s\_cb);if (rc != 0) {printf("ams: starting the client failed (%d)\n", rc);}}void sample\_ams\_stop(void) {pbl\_bt\_ams\_client\_stop(&s\_client);}
```

Kconfig

```
mainmenu "iOS clients sample"

source "Kconfig.pebbleos"

config SAMPLE_ANCS
    bool "Notifications, with the ANCS client"
    default y
    select BT_ANCS_CLIENT

config SAMPLE_AMS
    bool "Media, with the AMS client"
    default y
    select BT_AMS_CLIENT
```

prj.conf

```
CONFIG_CONSOLE=y
CONFIG_CONSOLE_STDOUT=y
CONFIG_FLASH=y
CONFIG_FS=y
CONFIG_SETTINGS=y
CONFIG_NIMBLE=y
CONFIG_NIMBLE_STORE_CONFIG=y
CONFIG_NIMBLE_BLE_SM_SC=y
CONFIG_NIMBLE_BLE_SM_BONDING=y
CONFIG_NIMBLE_BLE_SM_OUR_KEY_DIST=3
CONFIG_NIMBLE_BLE_SM_THEIR_KEY_DIST=3
```

### Output

```
ios_clients: advertising as PebbleOS
```

Generated from PebbleOS [4bbc630fa](https://github.com/coredevices/pebbleos/commit/4bbc630fa451369e352c06b8276c7fe37c67f4fd). This page is maintained in the pebbleos repository: [docs/samples/subsys/bluetooth/ios\_clients.md](https://github.com/coredevices/pebbleos/blob/4bbc630fa451369e352c06b8276c7fe37c67f4fd/docs/samples/subsys/bluetooth/ios_clients.md).
