bluetooth.servegatt(services)

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;
                    }
            }
        ]
    }
]);