The purpose of this functionality is to identify a driver or passenger in vehicles using their smartphone through Bluetooth Low Energy communication.

This functionality involves different parts:

• Ekko GraphQL API that manages the link between the car, smartphone, and device, and generates tokens for authentication.
• Smartphone Application developed by the customer that communicates with MUNIC devices to authenticate using generated tokens.
• MUNIC Application on the device that identifies the smartphone, validates its token, and reports the presence of nearby Bluetooth devices.

The first step is to use the Ekko GraphQL API to generate the different entities, link them, and generate authentication tokens.

The second step is to use the generated token in the customer's smartphone app to pair and recognize the device.

The final step is that the device will automatically recognize the paired smartphone and report known devices as soon as it is nearby.

You can find below the link to the Ekko GraphQL API documentation:

When the phone is connected to the dongle via Bluetooth, the strength of the signal (RSSI) can be used to estimate distance.

• Zone 1: Within the vehicle — signal strength higher than min_rssi_connect.
• Zone 2: Outside but close to the vehicle — signal strength between min_rssi_connect and min_rssi_disconnect.
• Zone 3: Out of range — signal strength below min_rssi_disconnect.

Create Driver

Use the driver_create mutation to create a driver.

Required Fields

• label (String): Full name of the driver (max 64 characters).

Optional Fields

• id_key (String): External system ID (max 64 characters).
• default_vehicle_id, user_contact_id, user_profile_id: Not used or set automatically.

Example Mutation

mutation driver_create(
  label: "Bob MORANE",
  id_key: "DR_123456"
) {
  id
}

Example Response

{
  "id": "549125678971651458"
}

Use the drivers query to retrieve existing drivers.

Associate Smartphone and Driver

Use the post_driver_auxiliary_devices mutation to link a smartphone.

Required Fields

• driver_id: ID returned from driver creation.
• input.data.type: Must be auxiliary_devices.
• input.data.attributes.label: Brand/model of phone.
• input.data.attributes.kind: Must be phone.

Example Mutation

mutation post_driver_auxiliary_devices(
  driver_id: "549125678971651458",
  input: {
    data: {
      type: auxiliary_devices,
      attributes: {
        label: "Apple Iphone 16",
        kind: phone,
        id_key: "PH_123456_001"
      }
    }
  }
) {
  ... on auxiliary_device_show {
    data { id }
  }
  ... on errors {
    errors { title, code }
  }
}

Example Response

{
  "data": {
    "id": "1012300605301948418"
  }
}

Settings Object Fields

• min_signal_power_connect (Int):  

  An integer between -127 and 127 representing the minimum RSSI value (in dBm) required for the device to be considered "connected."  

  > Note: If you provide this, min_signal_power_disconnect is also required.

• min_signal_power_disconnect (Int):  

  An integer between -127 and 127 representing the RSSI value (in dBm) below which the device will be considered "disconnected."  

  > Note: If you provide this, min_signal_power_connect is also required.

• max_time_idling_disconnect (Int):  

  The time in seconds (an integer between 0 and 1800) that a device can remain idle with a low signal before being disconnected.

Example

settings: {
  min_signal_power_connect: -85,
  min_signal_power_disconnect: -95,
  max_time_idling_disconnect: 60
}

Associate Driver and Vehicle(s)

Use the add_driver_authorized_vehicles mutation to link driver and vehicle(s).

Example Mutation

mutation add_driver_authorized_vehicles(
  id: "549125678971651458",
  input: {
    data: [
      { type: vehicles, id: "947459018033856520" }
    ]
  }
) {
  ... on Void_container { Void }
  ... on errors {
    errors { title, code }
  }
}

Fetch the Authentication Token

Use the put_driver_auxiliary_device mutation to retrieve a Bluetooth token.

Example Mutation

mutation put_driver_auxiliary_device(
  driver_id: "549125678971651458",
  aux_id: "1012300605301948418",
  input: {
    data: {
      type: auxiliary_devices,
      id: "1012300605301948418",
      attributes: {
        action: renewToken,
        token_max_ttl: 86400
      }
    }
  }
) {
  ... on auxiliary_device_show {
    data {
      type,
      id,
      attributes {
        bluetooth_token
      }
    }
  }
  ... on errors {
    errors { title, code }
  }
}

Example Response

{
  "data": {
    "type": "auxiliary_devices",
    "id": "1012300605301948418",
    "attributes": {
      "bluetooth_token": "..."
    }
  }
}

Token is valid for 15 minutes by default if token_max_ttl is not used.

Delete a Phone from a Driver

Use the delete_driver_auxiliary_device mutation.

Example

mutation delete_driver_auxiliary_device(
  driver_id: "549125678971651458",
  aux_id: "1012300605301948418"
) {
  ... on Void_container { Void }
  ... on errors {
    errors { title, code }
  }
}

The smartphone app sends the token over Bluetooth LE to authenticate with the dongle.

Manual or Automatic Pairing

• Manual: Scan for BLE devices with names like MUNIC_XXXXXXXXXXXYY.
• Automatic: Listen for BLE advertisements with UUID 0000183D-0000-1000-8000-00805F9B34FB.

Bluetooth LE Authentication

• GATT Service UUID: 0000183D-0000-1000-8000-00805F9B34FB
• Characteristics:
  • Payload: 8ba5d3a5-b597-4ff7-ae8d-6a47b34c6d88
  • Push: 8ba5d3a6-b597-4ff7-ae8d-6a47b34c6d88

Send token via Payload, then write 1 to Push to validate.

Developer Documents

Test with nRF Connect

Use the nRF Connect app to test the Bluetooth connection and token authentication.

Testing Guide

Pokes from sender auxiliary_device, namespace nearby_device::report.

Connection Poke

Example:
json
{
"reported_at": "2025-02-03T14:34:37.553Z",
"vehicle_id": "1011173885573070849",
"connections": {
"device_connections": [
"known_device": {
"driver_id": "...",
"driver_id_key": "...",
"rssi": -25,
"tx_power": -25,
"last_seen": "...",
...
"status": "NEARBY"
}
]
}
}


Fields

Nearby Poke

Example:
json
{
"reported_at": "2025-02-03T12:34:56.789Z",
"vehicle_id": "...",
"nearby_devices": {
"known_devices": [...],
"unknown_devices": [...]
}
}


Why aren’t phones listed in unknown devices?

The unknown devices list is the result of a Bluetooth scan performed by the dongle.

During the scan, nearby Bluetooth devices that are actively sending advertisements will be recorded and sorted by signal strength.

Phones typically do not send advertisements unless an application explicitly enables it. As a result, phones are usually excluded from the unknown_devices list.

Phones that are connected and paired will instead appear in the known_devices list.

How to adjust signal sensitivity?

You can modify the min_rssi_connect and min_rssi_disconnect thresholds when generating the token. These values define the sensitivity zones for Bluetooth proximity.

Last update: 17/07/2025