Skip to content

Generic Access Profile (GAP) and Omnivoltaic GATT Design

Overview

This document provides an in-depth look at the Generic Access Profile (GAP), focusing on the modes and roles of BLE devices, advertising parameters, and key features of Omnivoltaic's GATT Design. It outlines essential services, such as the ATT Service for device attributes, CMD Service for operational commands, and various diagnostic and data services necessary for efficient device management and communication.

Sections:

  1. Generic Access Profile (GAP)

    • Modes & Roles of BLE Devices: Overview of device roles (advertiser, scanner, central, peripheral) and the connection establishment process.
    • Advertising Events: Explanation of advertising event types, including Connectable and Scannable Undirected Event.
    • Advertising Parameters: Discussion on key advertising parameters like Advertising Interval, Service Solicitation, and Appearance.

  2. Omnivoltaic GATT Design

    • General Guidelines: Key practices for designing GATT services, including using vendor SDKs, grouping characteristics, and optimizing UUIDs.
    • GAP Service: Explanation of the Device Name and Appearance characteristics, with guidelines on setting them using vendor SDKs.
    • ATT Service - Device Attributes: Overview of the attributes, such as OEM ID and PAYG ID, with example data.
    • CMD Service - Commands: A look at operational commands like Input PAYG Credit Token and example data for commands like _pubk and _swch.
    • STS Service - Common Device States: Explanation of the service used to monitor device states, with example state data.
    • DTA and DIA Services: Description of DTA for data collection and storage, and DIA for diagnostics, with common use cases and example API operations.

Modes & Roles of BLE devices.

  • Advertisements (advertising, scanning, advertising parameters, advertising data, scanning parameters).
  • Connection establishment (initiating, accepting, connection parameters)
  • Security. This repo collects all device-discovery related protocols, including messaging mechanism cross all devices, and specific device data formats
  • Advertising Events

An advertising event is made up of multiple advertising packets being sent on all, or a subset of, the three Primary Advertising Channels (37, 38, and 39). For Omnivoltaic eIoT, the following advertising event is used: - Connectable and Scannable Undirected Event: This type allows other devices to receive the advertisement packets, send a scan request to the advertiser, and establish a connection with it.

Advertising Parameters

  1. Advertising Interval
  2. Advertising/Scan Response Data
  3. Service Solicitation: a list of one or more UUIDs indicating what services are supported and exposed by the deviceʼs GATT server. This helps central devices learn the available services (explained in a later chapter) exposed by a device before establishing a connection.
  4. Appearance: this defines the external appearance of the device according to the Bluetooth Assigned Numbers.

These include appearances such as phone, heart rate sensor, key ring and many more. If you cannot find an appearance that fits the nature of your device, you can use the UNKNOWN APPEARANCE value.

Omnivoltaic GATT Design

General Guidelines

The following mandatory service and its characteristics:

  • Generic Access Profile (GAP) service.
  • Name and Appearance characteristics within the GAP service.
  • Use vendor SDKs APIs for setting the name and appearance. The SDK then handles creating the GAP service and setting the characteristics according to the user-provided values.

Utilize the Bluetooth SIG-adopted profiles, services, and characteristics in your design whenever possible. This has the following benefits: - You get the benefit of reducing the size of data packets involving UUIDs for services and characteristics (including advertisement packets, discovery procedures, and others) and since 16-bit UUID values are used instead of 128-bit values. - Bluetooth chipset and module vendors usually provide implementations of these profiles, services, and characteristics in their SDKs and reducing development time considerably. - Interoperability with other third-party devices and applications, allowing more devices to interface with your device and provide a richer user experience. Group characteristics that serve related functionality within a single service. Avoid having services with too many characteristics. - A good separation of services makes it faster to discover certain characteristics and leads to a better GATT design that is modular and user-friendly.

GAP Service:

Device name characteristic: "Device Name". Access permissions: Read. Appearance characteristic. Access permissions: Read.

ATT Service - Device Attributes

ATT Service (Device Attributes): This service handles device-specific identification attributes.

  1. Device OEM ID ("opid")
  2. Purpose: Stores the manufacturer's unique identifier for the device
  3. Access: Read-only
  4. Example
"_att" : {
"_meta": "Attributes are immutable once set, typically at factory",
"_opid": "OEM Device ID. Factory set.",
"_ppid": "PAYG Device ID. Factory set. Field override options.",
"_flid": "Fleet ID. Factory set. Field override options.",
"_frmV": "Firmware Version. Factory set."
},

  1. Device PAYG ID ("ppid")

  2. Purpose: Stores the Pay-As-You-Go identifier for the device

  3. Access: Read-only

  4. Example

"att" : {
"opid" : "12AH20000001",
"ppid" : "12AH20000001",
"flid" : "60b032fa3711d64a5c6c22a7",
"frmV" : "1.0"
},

CMD Service - Commands

CMD Service (Commands): This service handles operational commands for the device.

  1. Input PAYG Credit Token ("pubk")
  2. Purpose: Allows adding credit tokens for Pay-As-You-Go functionality
  3. Access: Read and Write
  4. Example
"_cmd" : {
"_meta": "Commands are values writed by external client.  Also readable",
"_pubk": "Public Key / Last Code",
"_gstw": "GPRS Sleep Time Window in mins",
"_gctw": "GPRS Connect Time Window in mins",
"_raml": "Rapid Auto Message List",
"_ramt": "Rapid Auto Message Time in Second"
"_alml" : "Abacus Ledger Message List"
"_napn": "GPRS Carrier APN Name and Passcode",
"_swch": "Generic device switch swch = ON | OFF ",
"_read": "Last read request of ANY GATT <data> = [opid|...|]",
"_rptm": "Set notification request <mode> = [0|1|2|3|4], 0: Auto-Periodic | 1 = Request-Response | 2 = Change-Notification",
"_hbfq": "Heart Beat Interval Minutes"
},
  • Data example
"cmd" : {
"pubk" : "*042 195 826 493 279 052 222#",
"gstw" : 480,
"gctw" : 10,
"raml" : ["plat", "plon", "pckc"],
"ramt" : 10,
"alml" : ["pckc", "batp"],
"napn" : "t-mobile,xxxxxxx",
"swch" : "On",
"read" : "<data>",
"rptm" : "<Rpt mode>",
"hbfq" : 60
},

STS Service - Common Device States

STS Service (Common Device States):

  • Purpose: Manages and monitors general device states
  • Note: Additional details about specific states would be needed to provide examples
"sts" : {
    "sstc" : 1,
    "crtm" : 202100010001,
    "udtm" : 202100010002,
    "time" : 202100010003,
    "plat" : 37.177,
    "plon" : -121.7549,
    "gpss" : 4,
    "gpfc" : 100,
    "rcrd" : 1,
    "trhd" : 1,
    "tpgd" : 1,
    "pgst" : "PAYG",
    "tkre" : "NEW",
    "ocst" : "ENABLED"
},

STA Service (Status):

  • Purpose: Provides current status information about the device
  • Note: Additional details about specific status parameters would be needed to provide examples

TST Service (Testing and Diagnostics):

  • Purpose: Used for running diagnostic tests and retrieving test results

DTA Service:

DTA Service - Data

  • Purpose: This service handles data collection, storage, and retrieval operations
  • Common use cases: Reading sensor values, storing measurements, retrieving historical data Example operations:
# Reading current sensor data
GET /dta/current
Response: {
    "temperature": 25.6,
    "humidity": 65,
    "voltage": 12.3,
    "timestamp": "2025-02-11T14:30:00Z"
}
# Storing a new data point
POST /dta/store
Body: {
    "sensor_id": "TEMP01",
    "value": 25.6,
    "unit": "C"
}
# Retrieving historical data
GET /dta/history?start=2025-02-10&end=2025-02-11
Response: [
    {
        "timestamp": "2025-02-10T14:00:00Z",
        "temperature": 24.5
    },
    {
        "timestamp": "2025-02-10T15:00:00Z",
        "temperature": 25.1
    }
]

DIA Service - Diagnostics

  • Purpose: Provides detailed diagnostic information and system health checks
  • Used for: Troubleshooting, maintenance, and system monitoring Example operations:
# Get system health status
GET /dia/health
Response: {
    "status": "OK",
    "uptime": "72:14:33",
    "memory_usage": "45%",
    "cpu_load": "23%"
}
# Run diagnostic test
POST /dia/test
Body: {
    "test_type": "connectivity",
    "parameters": {
        "target": "server1",
        "timeout": 30
    }
}
# Get diagnostic logs
GET /dia/logs?level=ERROR
Response: [
    {
        "timestamp": "2025-02-11T14:15:00Z",
        "level": "ERROR",
        "component": "GPRS",
        "message": "Connection timeout"
    },
    {
        "timestamp": "2025-02-11T14:16:00Z",
        "level": "ERROR",
        "component": "Sensor",
        "message": "Reading out of range"
    }
]
# Get component status
GET /dia/component/gprs
Response: {
    "status": "ACTIVE",
    "signal_strength": "75%",
    "last_connection": "2025-02-11T14:30:00Z",
    "errors": []
}

Common use cases:

  1. Data Service (DTA):
    • Regular sensor data collection
    • Data logging for compliance
    • Historical trend analysis
    • Real-time monitoring
  2. Diagnostic Service (DIA):
    • System troubleshooting
    • Performance monitoring
    • Error logging and analysis
    • Preventive maintenance
    • Remote system health checks