# Beardware x CAREDOSE API Doc

Thiswill be the go-to document for all the API level documentation of the Smart Dispenser and CAREDOSE Backend

# Backend
## SMS Communication Format
The format of the SMS communication is designed to keep the character count at a minimum.

The job of the dispenser is to:

1. Patient user adherence back to the server
2. Receive a block of data on startup with instructions on when to dispense medicines

### From Box to Server (1)

Each command is separated into a **command** and a **value**. A string of such messages delimited by a **#** make up the entire communication.

Times are in 24-hour format *without* a separator in between (again, in the interest of character space saving)

The **command** can be a simple letter that will tell the server what is going on, whilst still keeping some flexibility for programming in further commands or sending things out of order. Assuming this will work as of this first draft of this document, the proposed command letters are:

| command letter | function |
|----------------|-------------|
| a | Adherence |
| b | Battery |
| c | Carefill ID |
| d | Dose ID |
| e | Error Code |

For example:

a2240#b80#d771912

This tells us the dose with id 771912 was consumed at 22:40 and the dispenser has a current battery life of 80%

In the case of multiple values for each command, a **:** can be used to delemit them. For example:

a2240#b80#d771912#e3:87:91

This tells us the dose with id 771912 was consumed at 22:40 and the dispenser has a current battery life of 80% and the box has currently experienced errors 3, 87, and 91.

### From Server to Box (2)
This is a trickier question. Doses can be on a weekly basis or at odd times as well (Like some doses should only dispense every Sunday, or once on the 15th of each month, or 15th and 25th of each month). This means we would have to send dose level information instead of day level information that can be repeated for every dose.

Day level information is far more character-cost effective, but dose level information is more detailed and outirght necessary sometimes. It is proposed to support both kinds of information, and that will be in the following formats:

####Dose Level
Dose level information will just be a set of unix timestamps that can be easily parsed into times. These will be delimited by a **:**. For example:

0:1553690727:1553691727:1553692727:...e:1553699727

0: denotes the starting message

e: denotes the ending message

**If required for sequencing, each message going can start with a number (like 0:xxx 1:xxx 2:xxx) that will make it trivial to stitch the entire command.**

Although it may cost up to 10 SMSs to give the entire dose information, it makes sense to keep it this way to be absolutely precise.

## Smart Dispenser
Each Smart Dispenser should have a unique ID (we can perhaps use the unique chip ID that comes with each processor).

This ID is referred to as {unique_id} in this document.

### Getting the Carefill ID
The Carefill ID is built into the carefill RFID sticker which the dispenser should read and save. Ideally it should be read every single time the sync button is pressed to ensure it is present.

For button presses:

* SOS
* ```sos:{unique_id}```
* Alarm Stop
* This should be an internal setting
* Force Dispense
* If it is dispensed and cut, it should send the adherence data of the *last* dose that was cut. By simple server side logic, we can mark the the doses in the middle as well, as all our dose ids are serial.
* If it is not cut and only dispensed, it should remember that in the smart dispenser itself and not dispense the next *x* doses as they were already dispensed.
* Force Retract
* This is an internal state as nothing had been cut
* Force Sync
* ```sync:{carefill_id}```

### Clearing Schedules
There is no provision to clear your schedules as of now.

### Non Adherence
We can handle this server side to save battery life on the dispenser. If it won't take up too much battery, then handling it on the device is better because it will take up fewer processing cycles on the server. The tag would be:

na2240#b80#d771912

where *na* stands for non-adherence (in the format above)

### Getting Dose Information
You can send the sync command above to the server and it will reply with an SMS as mentioned above with all the relevant information.

### Error Codes
TBD