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.05
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.05 SUM: 1.07
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

121 thoughts on “Wearable integration API

    1. Is there a way to send sleep data over to withing app? I have the scale that covers everything and love the sleep app but would enjoy to integrate sending my sleep data over as well

          1. As customs of fit2 how can we push samsung to help help us? There are lot of us fit2 owners wanting this app and some of us are willing to push samsung

          2. Many thanks Brian, IMHO Samsung is not that kind of company which could be pushed by users. IMHO it is a big corporation which don’t care. We will tr your best to bring this as soon as possible. Beside the Fit 2 issue we are also fighting with the fact that actuall Samsung broke our sleep tracking integration on Gear S2 and all new Tizen devices altogether.

            The issues is caused by the recent firmware update to the Gear watches, which silently introduced background process freezing (Android doze mode alternative for Tizen). In effect, the sleep tracking is stopping intermittently throughout the night.
            We have been trying to find the cause for weeks, and finally it turned out that it was caused by this undocumented new feature of the underlying operation system on the watch.

            We have contacted Samsung about the issue, have exchanged a few emails and currently we are waiting if they can provide some pointers to a solution. It seems that they provide means to maintain a background process only to select developers. We may have to rewrite the whole app from Javascript-based to C-based one to solve the issues, but that would take a few weeks unfortunately.

            Workarounds:
            – please note that in the time being, you can still use sleep tracking using your phone’s accelerator sensor.
            – more over in the latest BETA version we introduced contact-less sleep tracking using ultrasound. If you are interested in giving it a try, please opt-in for our latest BETA version here:
            https://play.google.com/apps/testing/com.urbandroid.sleep
            – you can also consider using other smartwatches. At the moment we support Pebble with an incredible battery life. The watch last at least 5 days without charging with sleep tracking every day. Also Android Wear may be a good option too. With devices capable of sensor batching, sleep tracking only consumes ~15%-20% battery per sleep tracking.

  1. I’m curious if the Basis Peak is able to be supported. I love the features of this app but would prefer that my wearable transmit sleep data in lieu of having the phone on the bed. I also like having the smart alarm. The peak currently only has a set time alarm. I would rather have the app trigger the vibration at the appropriate time. Thanks.

    1. Hi, this is unfortunately impossible since Fitbit doesn’t provide a sufficient API. We cannot get accelerometer data from their API, so we cannot use their device.

      1. Any chance it will intergrate heart rate monitor? I love this app, but the lack of heart rate monitor, and the fact microsoft app sucks and the samsung Shealth doesn’t support band 2 i really hope it comes soon!

    1. Unfortunately Gear S2 has issues with battery life when doing a full night tracking sleep. It losses around 80% of battery per night. Samsung asked us to remove support for S2 from the Galaxy store. We are working with Samsung now so see whether we can return the app back to the store and if there are some technical solutions. Unfortunately we cannot distribute the app outside of Galaxy app store as this is a signature restriction build in by Samsung.

      Please check here for details:
      http://sleep.urbandroid.org/documentation/integration/wearable/

  2. Hi sleepasandroid team,

    I woyld like you to consider to integrate the fitbit charge hr into the app.
    Lot’s of people use this HR tracker and it would be a nice and usefull update if the data from the tracker is connected into the sleepasandroid app.

    Thanks in advance!

  3. Hi, I would like to know if the app works with Garmin Vivosmart. Vivosmart is a fitness band / smart watch which receive vibration alarm when there is phone call or message or any kinds of notification from the phone. Hope to hear from you soon. Cheers.

      1. I would also appreciate it if the Garmin Vivosmart would work with the Sleep As Android app as well.
        Especially since the Garmin Connect app allows for users to pull data from the Sleep As Android app already.

        1. Hello Debbie, unfortunately Garmin Vivosmart does not provide required integration options for the Vivosmart band. They only make their higher end devices available for connection via Connect IQ

  4. I was wondering if it’s possible to support Xiaomi mi band ? They are relatively cheap(15-25$) and could work as sleep tracing and smart alarm with prolonged battery life(30-45 days). Sleep as Android could benefit by supporting some cheaper band devices, not only watches. I like this App and bought it right away but I would like to replace my phone with a fitness band what seems impossible to me as “Sleep as Android” supports only watches.

        1. Mi Band is a really bad closed platform. The only aim of Xiaomi and theereason why the device is so cheap is that they want the data and the community for themselves only.
          They do whatever they can to avoid any 3rd party integration – which would be great for the users.

          Not only every reverse engineered knowledge is useless after each firmware update (because they change bluetooth commands entirely), in the latest firmware they even introduced encryption which makes only the official Mi Fit app able to talk to the Mi Band.
          We have tried hard to make this possible but due to the recent development I don’t want to spend any additional time on this. We are still negotiating with Zdenek Horak’s Mi Band tools if they can provide support for Sleep as Android’s sleep tracking but due to the recent changes I’m unsure he will still have the enthusiasm to invest into this any longer.

          Sorry about that, but it is time to look for another more open fitness tracker.

    1. Hi, I’m using the TomTom Runner 2, and was wondering if there is an API for that, how can I find out? Do you guys support the accelerator and hr monitoring for this device?
      Cheers,
      Bob

      1. Hi, with some companies it’s a rosegarden to find their API, with some it is big trouble to find out they have none.
        Unfortunately TomTom has stated somewhere on their support forum that they have no intention of publicising their API. If they follow the standard BTLE HR protocol, you can already use it for HR measurement with Sleep. Just try it (turn it on in Settings > Smartwatch > BT Smart heart rate)

  5. Your information said that I can sideload this app to work with Samsung Gear S2. I do not have the technical knowledge to do this. Please reconsider putting an updated app on the Samsung Tizen so I can use this with the S2.

    1. Hello, please check our forum to get an idea on how to do the sideloading. Unfortunately we don’t have access to an S2 other than a loaner device from Samsung (on which it works). We are waiting for Samsung to publish an updated version of their SDK so we can use sensor batching.

    1. Hello, unfortunately Fitbit does not give access to their accelerometric sensors, so we cannot use their data even though they have an API since we don’t know what they are sending us:/

  6. I only would like to ask if Pebble SmartWatch (301) is supported? I see pebble Classic is supported, but I don’t know if it is the same device, and I only buy for this purpose, so I don’t want to buy an unsupported watch.

    1. Hello, it is very difficult with Samsung. We’d like to support it, but it will take a long time (at least some months) since their app approval process is very painful.

  7. Any chance for 37 degree L18 or journey inchor+ ? These bands got sleep trackin, BP and HR monitors, so it will be great if u can integrate it.
    Sry, but I’m wroting it, when going sleep and I’m not an expert in English.

    1. Hello Michael, sorry about the delay in answering — do those devices have any API? Could you please find me a link? If there is no API, unfortunately we cannot support the device.

    1. Hello Stella, unfortunately their API isn’t sufficient – they provide already computed sleep data, so we could not add anything to it. They already compute the sleep phase and do not give out the raw motion values.

    1. Hello Monica, unfortunately Fitbit has a strict policy towards 3rd party developers with regard to integrations….it is not possible to get data from the device without large scale partnership with the company :/

      1. Hello Jiri!

        I realize that you cannot fetch sensor data from FitBits, but could you do the reverse and use the FitBit device to compliment the smart alarm functionality by pushing alarms to it?
        I found the Alarm creation API in their docs here: https://dev.fitbit.com/docs/devices/#alarms
        I do not know enough about Android development to create an addon myself, but I would happily help test if that is of use!

        You could make some of these integrations available to premium users only if that helps finance their creation. I am already a premium member but know some free users who would pay for the Unlock to get this feature alone. Alternatively have you considered “bounty” programs where users could sponsor a feature request by committing a certain amount of money?

  8. Can you please check if you are compatible or can integrate with this China Bracelet. It is everywhere.

    Shenzhen Bessky Technology “Model”: LFQ60308463BK
    On Box Model #: TW64S

    Heart rate exercise bracelet Sleep monitoring & more sold from $15:00 – $19.00

    It uses the App, “Mistep”. The only complaints are about how usless the App is. It is called cheap & unusable for Sleep data. The data is shown iin a poor format.

    NEWEGG sells these at:
    https://m.newegg.com/Product/index?itemnumber=9SIA5HV4FR7361

    Thank you,
    Chuck G.

    1. Hi Chuck, the bracelet has no public API other than the standard bluetooth, so it might be able to send heart rate to us and nothing else. For that, it would be already ready. If you have the bracelet, please check that by enabling Settings > Wearables > Bluetooth Smart

    1. Hello Paul, unfortunately the Vivosmart HR cannot be integrated since it is not a “Connect IQ” device – which means that 3rd party developers cannot create apps for it.

    1. Hello Caitlin, as far as I know, the Withings wearables don’t have any public API that we could connect to directly. They only have a web API which gives out aggregated data, not real-time accelerometric values. We need that kind of API for integration with Sleep as Android.

  9. Hi,I see on fitbit page thatthey hqve open API. I am using sleep as android for a while and received a fitbit as a gift.
    Why do you wrote somewhere in your docs for fitbit that there is no 3Rd party integration?
    Cheers

    1. Hi Joey, I went through their API and it seems that you can only get the data ex-post. But we need realtime data for smart wake up and other functionalities. Also Atlas does not give out raw motion data even ex-post, so I don’t see the way with Atlas currently…

  10. 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!

Leave a Reply

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