Wearable integration API

Who is the API intended for

If there is a 3rd party smartwatch you’d like to see integrated with Sleep, that does have some usable API and is not integrated yet, you have 2 options:

  1. Write us about the watch, and we’ll evaluate how useful and feasible would it be to integrate the watch with our application. if we are convinced it is feasible and many users would benefit from it, we’ll do the integration ourselves.
  2. You can try to integrate the watch yourself. You can even make your own paid add-on to sleep for other users if you want, we have no objections against this!

This section gives you necessary information about the integration hooks in our application.

High level overview

Any newly integrated devices will likely need some device-specific communication channel. You cannot write this as a part of our application. Instead, you should write a separate android application that will do 2 things. First, it will communicate with the watch of your interest. Second, it will communicate via standard android intent with Sleep As Android application. On this page you can find all the important intents you need to listen to and you can send.

Initiating connection to phone

When a phone needs to connect to your watch (start of tracking, alarm, ..) it first checks whether the watch is connected. It will issue the following intent:
com.urbandroid.sleep.watch.CHECK_CONNECTED
The intent is issued periodically every few seconds either till a positive reply is issued or timeout has passed. You should listen to this intent and reply with the following intent when the watch is connected and ready to be used:
com.urbandroid.sleep.watch.CONFIRM_CONNECTED
After this exchange the phone is ready to use the smartwatch for further actions.

Initiating connection from watch

Watch can automatically establish the connection with the phone application by sending some sleep movement data, see later. When this is done, the tracking on phone is automatically started and the connection between the watch and phone is prepared to receive further updates.

Commands from phone

There is a fixed set of commands sent from the phone to the watch you need to implement. You do not need to implement all of them, if you do not need all the features.

  • Start movement tracking
    Intent: com.urbandroid.sleep.watch.START_TRACKING
  • Stop movement tracking
    Intent: com.urbandroid.sleep.watch.STOP_TRACKING
  • Pause tracking
    Intent: com.urbandroid.sleep.watch.SET_PAUSE
    Params:
    TIMESTAMP (long): Timestamp in milliseconds that tells the watch till when the pause should last. It can be in the future, which means pause is still active, or in the past, which means pause should be terminated.
    When the pause is received, the watch should note the pause end-time. Till then, no tracking needs to be performed, but values of 0.0 should still be sent. It is advisable to show to a user the tracking is paused and indication of remaining pause time. User should be also given an option to extend or terminate the pause.
    If the pause expires naturally on phone, i.e. its time runs out, there is no notification to the watch about pause being over! Only if user prematurely finishes the pause, watch is notified (by sending SET_PAUSE with timestamp 0).
  • Suspend tracking
    Intent: com.urbandroid.sleep.watch.SET_SUSPENDED
    Params:
    SUSPENDED (bool): Whether the tracking is suspended or not.
    This is a complementary intent to SET_PAUSE. If you do not intend to show any pause indication or allow user to control pausing, you can just listen on SET_SUSPENDED. It is set to true when pause starts and set to false when the pause is over.
  • Set batch size
    Intent: com.urbandroid.sleep.watch.SET_BATCH_SIZE
    Params:
    SIZE (long): Desired batch size
    This command is used to request an a size of batch of events send from watch to the phone. If you do not obey the requested batch size, some data may get ignored or you may end up with holes in your graph. You should keep on your end record of the latest requested batch size.
    When you receive a change of desired batch size and it is higher than current batch size, just keep aggregating data till you reach desired batch size. If a new desired size is lower than current batch size, try to send data as soon as possible and new batch you build should be at most of the new desired size.
    See more details about handling of batch sizes in “Sending movement data” watch messages.
  • Start alarm
    Intent: com.urbandroid.sleep.watch.START_ALARM
    Params:
    DELAY (int): Desired delay in millisecond after how long should the alarm start.
    Send when an alarm should ring. The delay parameter is controlled by a watch gradual vibration configuration. It tells the watch, when a user would like the vibrations to start on the watch.
  • Stop alarm
    Intent: com.urbandroid.sleep.watch.STOP_ALARM
  • Set alarm
    Intent: com.urbandroid.sleep.watch.UPDATE_ALARM
    Params:
    HOUR (int): Hour of day, when the next alarm will ring.
    MINUTE (int): Minute of an hour, when the next alarm will ring.
    TIMESTAMP (long): Timesatmp (in ms), when the next alarm will ring.
    The first 2 params are more for presentation – useful especially for devices with lack of support for timezones. The third parameter is an actual timestamp when the alarm will ring. It can be used to ensure an alarm rings on the watch even if it is not connected to the phone (the watch can for example trigger the alarm themselves when the timestamp is reached). If the connection with phone is alive, the phone will sent the START_ALARM intent to notify the watch the alarm is ringing.
  • Show notification
    Intent: com.urbandroid.sleep.watch.SHOW_NOTIFICATION
    Params:
    TITLE (string): Title of the notification to be shown.
    TEXT (string): Text of the notification.
    This intent is used to show a generic notification on the watch. It is not required for tracking or alarm to work.
  • Hint
    Intent: com.urbandroid.sleep.watch.HINT
    Params:
    REPEAT (int): How many times should the hint signal be repeated.
    Used by watch to send a non-textual notification to user, typically implemented as a short vibration. In case of vibration, the REPEAT parameter tells the watch how many times show it vibrate. This command is send for example by lucid dreaming or anti-snoring features.

MESSAGES FROM WATCH

In this section we list a set of intents, that can be send to our application. Not all of them need to be implemented.

Send movement data
Intent: com.urbandroid.sleep.watch.DATA_UPDATE

Params:
 MAX_DATA (float array): Array containing latest MAX received values. Data should come in order in which they were received.
 MIN_DATA (float array): Array containing latest MIN received values. Data should come in order in which they were received.
 SUM_DATA (float array): Array containing latest SUM received values. Data should come in order in which they were received.

Sleep As Android expects to receive data aggregated per 10 seconds intervals. The values to be aggregated should be changes in raw accelerometer data expressed in m/s2. For each sampled value sum up acceleration change along all axis to get a single value. You should aggregate the per-sample data in 3 different ways – maximum, minimum, and average acceleration value seen in 10 seconds interval. For efficiency, we suggest you do the aggregation on the watch and send only aggregated values to the phone.
You should keep aggregating data as they come and when you have enough aggregated values (as many as requested batch size) send the to the application. If the batch is send too late, it may confuse the collection algorithm and values can be either ignored or a graph may already have an empty space filled.

Values should be send also in case the tracking is paused! You can send just -0.01 for each of the aggregate that fits to a time tracking was paused.

Example aggregation:
Let’s assume your device samples once every 5 seconds (for simplicity only – real devices sample a few times per second). Assume these values from accelerometer:
Time 0s – X: 9.81, Y: 0.0, Z: 0.0
Time 5s – X: 9.81, Y: 0.1, Z: 0.0
Time 10s – X: 9.81, Y: 0.2, Z: 0.0
Time 15s – X: 10.81, Y: 0.0, Z: 0.3
 
The values would transform to this:
Time 0s – we do not have any past values, so cannot compute diff -> ignore this.
Time 5s – 0.1
Time 10s – 0.1
Time 15s – 1.5
Finally, these has to be aggregated to 10 second batches. We have 20 secs of data, so they end up in 2 batches. The first aggregate has only one value as we had to ignore the first value, so the final values are:Aggregate 1 – MIN: 0.1, MAX: 0.1, SUM: 0.1

Aggregate 2- MIN: 0.1, MAX: 1.5 SUM: 1.7
The batches have to be send in this order.

Send HeartRate data
Intent: com.urbandroid.sleep.watch.HR_DATA_UPDATE

Params:
 DATA (float array): Array containing latest heart rate values. Data should come in order in which they were received.

The data are expected to be expressed in number of heart beats per minute. It is not necessary to sample these data so frequently as movement data. Once every few minutes is perfectly fine.


Pause from watch
Intent: com.urbandroid.sleep.watch.PAUSE_FROM_WATCH

Adds 5 minutes to current pause time.

Resume from watch
Intent: com.urbandroid.sleep.watch.RESUME_FROM_WATCH

Terminate current pause.

Snooze from watch
Intent: com.urbandroid.sleep.watch.SNOOZE_FROM_WATCH

Snooze current alarm.

Dismiss from watch
Intent: com.urbandroid.sleep.watch.DISMISS_FROM_WATCH

Dismiss current alarm. If there is a captcha enabled for current alarm, it will be displayed on the phone and has to be solved there. After the captcha is solved, the phone will send the STOP_ALARM action.

Share

159 thoughts on “Wearable integration API

  1. Hi guys, Ive had (paid version) of your app for a couple yrs & wld like 2 THANK YOU 4 all the work u put in2 integrating ANY& ALL devices who are willing to give u access to the info u need. I have a few questions..First, why are so many of these companies so weird about giving access to their APIs?! What do you assume their reasoning is behind being so stingy with it? lol..I used2 hava misfit until I lost it & wasnt abl2 use it with “Sleep as Android”. Then I got a Xaiomi Mi Band 1s (bc Id read so many positive reviews related to its sleep tracking, but personally I cannot understand how so many ppl had good experiences with it bc I’ve only had the Mi Fit app record ANY sleep data maybe 5 times in the few mts I’ve had it. I have however gotten very accurate sleep data from an app called “Notify & Fitness for Mi Band” which is a 3rd party app(and surprisingly FREE) so how do u suppose the dev is abl2 get the data needed 2 show that info? (I’ve emailed them regarding your app btw but haven’t gotten a reply. …I stopped writing here a few days ago and just came back to finish. I was planning on sending another email to the dev of the “Notify & Fitness 4 mi band” but this morn I looked at my sleep graph in”Sleep as Android” and noticed that it showed all the info that it normally showed b4 I linked my Mi Band to the app, so I’m wondering if you guys were successful with the re-engineering you’ve spoken of, or is it just picking up my movement etc from my phone being in my bed? I shld prob tell u that when I start sleep tracking it says “waiting for connectivity” and once it connects it shows a little Bluetooth icon, so that makes me think that it must be working with my Mi Band. Anyway, one last question: I also heard about Fitbit acquiring Pebble, and I did read ur comment above saying you still recommend Pebble, but do you suppose once all is said & done that Fitbit will start keeping all the Pebble devices data to themselves the way theyve done with Fitbit? I ask bc I’ve been looking into getting a Pebble but if you think it’ll eventually not work with”Sleep as Android” then I’ll kno 2 start looking into Garmin instead. Thx guys!

    1. Hi Mike, it might work for heart rate (not motion), if they have implemented standard bluetooth heart rate protocol. To try it, please enable Settings > Wearables > [Heart rate measurement] Bluetooth Smart

    1. They have released a device API for Fitbit Ionic so we are now able to integrate Fitbit Ionic and will do it once we find the time. Currently we are focused on this: sleepphaser.urbandroid.org

  2. Is Gear Fit 2 on the roadmap for compatibility. I’ve been using your app for 3 years and I love the insights the app provides, interface, functionality…..everything. It’s just such a shame I can’t use my wearable with your amazing app.

  3. Hello, are there plans to include Huawei watch with HR in your wearable devices list? I love the watch except that it doesn’t track HR automatically during sleep. I believe it uses Android wear because I had to download it when I first set it up. Any way you can help? Instructions on API are over my head. Thank you.

    1. Hi it should actually already work. You might be missing a body sensors permission. Please start Sleep as Android from the watch, it should ask you for the permission…

  4. Hi! I’m using an Iwown I5 Plus smart band, and I will buy the full version of the app, so I wanna know if it’s possible to track my sleep with my wearable. Thanks for your help 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *