Skip to main content

bluetooth.servegatt(services)

Configures the imp as a GATT server for specified services

Availability

Device
Only available on the imp004m and imp006 (impOS 42)

Parameters

Name Type Description
services Array of tables A set of services provided by the application

Returns

Nothing

Description

This method sets up a GATT server. The imp004m can support only one GATT server at any one time, and the server is available on all connections.

The server is deactivated by default; an active server can be deactivated by passing an empty array ([]) into the services parameter:

bt.servegatt([]);

services is an array of tables, each of which defines a service through the following keys:

Key Data Type Required? Description
uuid String Yes The UUID of the service
chars Array of Tables Yes A set service characteristic definitions (see below)

Each service characteristic is a table with the following keys:

Key Data Type Required? Description
uuid String Yes The UUID of the characteristic
value String or blob No A fixed value for the characteristic
read Function No A function which gets the characteristic’s value
write Function No A function which sets the characteristic’s value
flags Integer No A bitfield of values defined in the Bluetooth standard

If flags is not provided, it is automatically computed as follows:

  1. Start with an empty bitfield
  2. If value is provided, then set Read
  3. If read is provided, then set Read
  4. If write is provided, then set Write

read references a function that takes a btconnection object (see onconnect()) and must return a blob or a string. A Squirrel error is raised if if the wrong type is returned when a read is attempted. The example code below shows such a function in use.

write is a function that takes a btconnection object and a blob as its two arguments. It should return an integer error code chosen from the standard ATT error codes. Zero, or no return value, denotes success.

Note Squirrel tables and arrays are mutable data structures. These functions walk and convert the whole data structure before returning, so any changes to the passed-in value will not be reflected.

UUIDs

UUIDs are used extensively in GATT to name services, characteristics, descriptors, etc. In Squirrel, they are encoded as integers or strings/blobs as follows:

  • Integer — eg. 0x180f — A standard-range UUID encoded in 16 bits.
  • 32-byte String/Blob — eg. "0000180f00001000800000805f9b34fb" — A UUID encoded in hexadecimal.
  • 16-byte String/Blob — eg. "\x00\x00\x18\x0f\x00\x00\x10\x00\x80\x00\x00\x80\x5f\x9b\x34\xfb" — A UUID encoded as bytes in natural order.

All of the above examples refer to the same UUID representing “org.bluetooth.service.battery_service”.

Example Code

The following snippet exposes standard device information and battery services on an imp004m-based device:

bt.servegatt([
    { "uuid": 0x180a, // Device information service
      "chars": [
            { "uuid": 0x2a29, "value": "Electric Imp" },          // manufacturer name
            { "uuid": 0x2a25, "value": hardware.getdeviceid() },  // serial number
            { "uuid": 0x2a24, "value": imp.info().type },         // model type
            { "uuid": 0x2a26, "value": imp.getsoftwareversion() } // firmware version
        ]
    },
    { "uuid": 0x180f,  // Battery level service
      "chars": [
            { "uuid": 0x2a19, 
              "read": function(conn) {
                        local b = blob(1);
                        local battery_percent = hardware.vbat() / 4.2 * 100;
                        b.writen(battery_percent, 'b');
                        return b;
                    }
            }
        ]
    }
]);