Drop API

Discover the Drop API to implement it in your project or better understand how it works. If you are developing for Android, it is recommended to use the official Android API. Also make sure to read the Get started section before this one, it will give you a general overview of the functioning of a Drop and how to communicate with it.

API

Overview

Drops use Bluetooth Low Energy (BLE) to communicate with another device. If you are not familiar with the basics of BLE, check out the Bluetooth Developer Portal first.

The Drops advertise some data you can use to decide whether your application needs to connect or not, like the Drop Type which can help you to identify the drops compatible with your applocation. When you are connected to the drop, the advertising stops, so make sure to remain connected as least as possible. For more informations about this, check out the Advertising section.

The Drops use one service (Drop Service) which contains three characteristics (Message Commands, Box Commands and Drop Commands). Each characteristic is used for writing a request and reading the response. Here are the steps to send a command and read its response:

  1. Write the command in the appropriate characteristic.
  2. Wait for the ACK. After this, the drop starts processing your request.
  3. The drop notify the response on the same characteristic (only the first 20 bytes are notified).
  4. If the response is longer than 20 bytes, you might want to read the full characteristic.

Warning! No request should be sent before the previous response notification has been received and acknowledged, even if the two requests are performed on different characteristics. The behaviour of the drop is not defined if you do not abide by this rule.

Due to some hardware restrictions, it is currently impossible to use the Write Long Bluetooth feature. However, we have implemented a workaround to let devices write commands longer than 20 bytes. See Long Commands section to learn how to use it.

Some commands also require the user to be authenticated as the administrator or as a user with priveleges. Check the Authentication section for more informations about it.

Advertising

The Drops are advertising every 0.5 seconds. The advertising packet contains the default BLE advertising fields (like the Drop name), and also some informations about the drop in the manufacturer specific data.

The manufacturer specific data field consists of 6 bytes organized like this:

Drop Type Revision Current timestamp X
00000000
0x00
Drop Type
Code used by the applications to identify the compatible drops.
Revision
Not yet used.
Current timestamp
Last timestamp registered by the drop.
X
Not used.

Message Commands

Fields

The Message Commands contain this header (8 bytes) followed by an optional content (its length is given by the Length/Error field). Read the specific documentation of a command to know how to configure these fields.

LE [0] Code S LE [1..8] X Box ID Message ID [0..8] - Message ID [8..14] Timestamp [0..7] Timestamp [8..15] Timestamp [16..23]
0000000000000000000000000000000000000000000000000000000000000000
0x000x000x000x000x000x000x000x00
Signed (S)
Set to 1 if the command is signed (see Authentication section for more informations).
Code
Code of the command to execute.
Length/Error (LE)
Length of the Content field. Set to 0x1ff if an error occurs.
Message ID
ID of the message.
Box ID
ID of the box where the message is stored.
Timeout
Timeout of the message.
X
Not used.

Read Message

Read the message with the given ID in the given box.

Authentication This command supports authentication. It can be runned as authenticated user or as admin. See Authentication section for more informations.

Request

Signed
Set to 1 if the command is signed (see Authentication section for more informations).
Code
0x00
Length/Error
0x00
Message ID
Set to the message ID you want to read.
Box ID
Set to the box ID where the message is stored.
Timeout
0x00
Content
Empty.

Response

Only the following fields are modified:

Length/Error
0x1ff if an error occured. Length of the content in bytes otherwise.
Timeout
Timeout of the message.
Content
If an error occured, it contains the error code on 4 bytes. Otherwise, it contains the content of the message (check the Length/Error field to know the length of the content).

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x16
Box not found.
0x17
Message not found.
0x1f
Invalid length (check the syntax of your command).
0x22
Not authorized (perhaps do you need to sign your request?).
0x35
Bad signature.

Write Message

Create a new message in the given box.

Authentication This command supports authentication. It can be runned as authenticated user or as admin. See Authentication section for more informations.

Request

Signed
Set to 1 if the command is signed (see Authentication section for more informations).
Code
0x01
Length/Error
Length of the Content field in bytes (less than 500 bytes).
Message ID
0x00
Box ID
Set to the box ID where the message is stored.
Timeout
Set the timeout of the message. Set to 0xffffff for infinite timeout.
Content
Content of the message. It cannot be more than 500 bytes long.

Response

Only the following fields are modified:

Length/Error
Set to 0x1ff if an error occured.
Message ID
ID of the created message.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x16
Box not found.
0x1f
Invalid length (check the syntax of your command).
0x22
Not authorized (perhaps do you need to sign your request?).
0x35
Bad signature.

Delete Message

Delete the message with the given ID in the given box.

Authentication This command supports authentication. It can be runned as authenticated user or as admin. See Authentication section for more informations.

Request

Signed
Set to 1 if the command is signed (see Authentication section for more informations).
Code
0x02
Length/Error
0x00
Message ID
Set to the message ID you want to delete.
Box ID
Set to the box ID where the message is stored.
Timeout
0x00
Content
Empty.

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured. Length of the content in bytes otherwise.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x16
Box not found.
0x17
Message not found.
0x1f
Invalid length (check the syntax of your command).
0x22
Not authorized (perhaps do you need to sign your request?).
0x35
Bad signature.

Edit Message

Modify the message with the given ID in the given box.

Authentication This command supports authentication. It can be runned as authenticated user or as admin. See Authentication section for more informations.

Request

Signed
Set to 1 if the command is signed (see Authentication section for more informations).
Code
0x03
Length/Error
Length of the Content field in bytes (less than 500 bytes).
Message ID
Set to the message ID you want to modify.
Box ID
Set to the box ID where the message is stored.
Timeout
Set the timeout of the message. Set to 0xffffff for infinite timeout.
Content
Content of the message. It cannot be more than 500 bytes long.

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured. Length of the content in bytes otherwise.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x16
Box not found.
0x17
Message not found.
0x1f
Invalid length (check the syntax of your command).
0x22
Not authorized (perhaps do you need to sign your request?).
0x35
Bad signature.

Box Commands

Fields

The Box Commands contain this header (3 bytes) followed by an optional content (its length is given by the Length/Error field). Read the specific documentation of a command to know how to configure these fields.

LE [0] Code S LE [1..8] X Box ID
000000000000000000000000
0x000x000x00
Signed (S)
Set to 1 if the command is signed (see Authentication section for more informations).
Code
Code of the command to execute.
Length/Error (LE)
Length of the Content field. Set to 0x1ff if an error occurs.
Box ID
ID of the box where the message is stored.
X
Not used.

Create Box

Create a new box with the given ID.

Admin This command must be signed by the administrator. See Authentication section for more informations.

Request

Signed
1
Code
0x00
Length/Error
0x06
Box ID
Set to the ID of the box you want to create.

The Content field must contain the following parameters for the new box:

Permissions Box size [0..7] Max message length [0..3] Box size [8..11] Delete mode Flood mode Max message length [4..8] Box mask
000000000000000000000000000000000000000000000000
0x000x000x000x000x000x00

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x1f
Invalid length (check the syntax of your command).
0x22
Not authorized (you must sign your request as admin).
0x35
Bad signature.

Delete Box

Delete the given box.

Admin This command must be signed by the administrator. See Authentication section for more informations.

Request

Signed
1
Code
0x01
Length/Error
0x00
Box ID
Set to the box ID you want to delete.
Content
Empty.

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x16
Box not found.
0x1f
Invalid length (check the syntax of your command).
0x22
Not authorized (you must sign your request as admin).
0x35
Bad signature.

List Message IDs

List the IDs of the messages stored in the given box.

Warning! The list may contains IDs of messages whose timestamps have expired. If you need to be sure about the validity of a message, you have to explicitly read it.

Request

Signed
0
Code
0x02
Length/Error
0x00
Box ID
Set to the box ID you want to list.
Content
Empty.

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured. Length of the content in bytes otherwise.
Content
Contains the list of message IDs. Each ID is stored on 2 bytes.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x16
Box not found.
0x1f
Invalid length (check the syntax of your command).

Drop Commands

Fields

The Drop Commands contain this header (2 bytes) followed by an optional content (its length is given by the Length/Error field). Read the specific documentation of a command to know how to configure these fields.

LE [0] Code S LE [1..8]
0000000000000000
0x000x00
Signed (S)
Set to 1 if the command is signed (see Authentication section for more informations).
Code
Code of the command to execute.
Length/Error (LE)
Length of the Content field. Set to 0x1ff if an error occurs.

List Box IDs

List the IDs of the available boxes.

Request

Signed
0
Code
0x01
Length/Error
0x00
Content
Empty.

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured. Length of the content in bytes otherwise.
Content
Contains the list of box IDs. Each ID is stored on 1 byte.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x1f
Invalid length (check the syntax of your command).

Drop Public Key

Return the public key of the Drop.

Request

Signed
0
Code
0x02
Length/Error
0x00
Content
Empty.

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured. 0x20 otherwise.
Content
The Drop public key (on 32 bytes).

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x1f
Invalid length (check the syntax of your command).

Sign

Sign the given content with the Drop private key.

Request

Signed
0
Code
0x03
Length/Error
Length of the Content field in bytes (less than 64 bytes).
Content
The content to sign. It cannot be more than 64 bytes long.

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured. 0x20 otherwise.
Content
The signature of the given content (on 32 bytes).

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x1f
Invalid length (check the syntax of your command).

Factory Reset

Reset the drop by removing all the boxes and all the messages. It can also revoke the Drop keys (a new key pair will be generated) and the administrator public key (the default admin key will be installed).

Use with caution! This command will erase all the boxes and messages stored in the box. There is no way to recover them after running this command. Also, depending on the parameters you give, this command may revoke the Drop keys and the administrator public key.
Warning! This command will disconnect your device instantly. Also this command takes up to 100 seconds to be performed. During the process, the led is on. Do not try to connect the drop while the led is on.
Admin This command must be signed by the administrator. See Authentication section for more informations.

Request

Signed
1
Code
0x05
Length/Error
0x01
Content
0x00 to preserve the Drop and Admin keys.
0x01 to reset the Drop keys and preserve the Admin key.
0x02 to preserve the Drop keys and reset the Admin key.
0x03 to reset the Drop and Admin keys.

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x1f
Invalid length (check the syntax of your command).
0x22
Not authorized (you must sign your request as admin).
0x35
Bad signature.

Change Drop Type

Change the type of the Drop which will be advertised.

Admin This command must be signed by the administrator. See Authentication section for more informations.

Request

Signed
1
Code
0x06
Length/Error
0x01
Content
The Drop type to advertise (on 1 byte).

Response

Only the following field is modified:

Length/Error
0x1ff if an error occured.

Error codes

If an error occurs, the Length/Error field is set to 0x1ff and the Content field contains one of the following error codes:

0x1f
Invalid length (check the syntax of your command).
0x22
Not authorized (you must sign your request as admin).
0x35
Bad signature.

Long Commands

Due to some hardware restrictions, it is currently impossible to use the Write Long Bluetooth feature. However, we have implemented a workaround to let devices write commands longer than 20 bytes. If the command is not longer than 20 bytes, no special behaviour is required. Otherwise, you must abide by the following rules.

A Long Command must be split into 20 bytes chunks. The first chunk is not modified. The others must start with the index of the chunk (the index starts at 1 for the second chunk). Here is an example of a Long Command before and after splitting (the index is highlighted): 

Before split:
071a010100ffffff000000020100000000000000000000000000000000deadbeef581c748ab1c7a725824ef3ba4d823626626c6120626c6120626c614fce49ca303d1794eb1ec75d876828b96745f456d74f84d114231d6e5fc89ec5ffff

After split:
071a010100ffffff000000020100000000000000   <-- 1st chunk, no index, 20 bytes of actual content
01000000000000000000deadbeef581c748ab1c7   <-- 2nd chunk, index 01, 19 bytes of actual content
02a725824ef3ba4d823626626c6120626c612062   <-- 3rd chunk, index 02, 19 bytes of actual content
036c614fce49ca303d1794eb1ec75d876828b967   <-- 4th chunk, index 03, 19 bytes of actual content
0445f456d74f84d114231d6e5fc89ec5ffff       <-- 5th and last chunk, index 04, 19 bytes of actual content

Be careful with the following points:

  • The index is written is hexadecimal (the chunk after 09 is 0a).
  • No padding is required for the last chunk.
  • A command which is exactly 20 bytes long does not need to be split.
  • A command which is exactly 39 bytes long requires 2 chunks (and not a third empty one).
  • If the command is signed, you must split your command after appending the signature. Also, given the length of a signature, all the signed commands are also Long Commands.
  • If the sent index is not the one the Drop was expecting, it will return a 0x20 error.
  • If anything else does not respect these rules, the Drop will return a 0x1f error.