5.9 KiB
+++ title = "API" date = 2021-10-23T23:04:51-07:00 weight = 2 +++
This page documents the API of ITD's control socket.
Request format
Request sent to ITD's socket should be valid JSON with the following format:
| Field | Type |
|---|---|
| type | int |
| data | any |
Example:
{"type": 5, "data": {"title": "title1", "body": "body1"}}
Sends notification titled "title1" with a body "body1".
Response format
Responses received from ITD will be valid JSON and have the following format:
| Field | Type |
|---|---|
| type | int |
| value? | any |
| msg? | string |
| id? | string |
| error | bool |
(Fields marked with "?" may not exist in all responses)
Examples:
{"type":1,"value":66,"error":false}
{"type":6,"msg":"Data required for settime request","error":true}
{"type":6,"error":false}
Requests
This section will document each request type, its response, and what data it needs.
Heart Rate
The heart rate request's type is 0. It requires no data and returns a uint8 in its value field.
Example request:
{"type":0}
Example response:
{"type":0,"value":92,"error":false}
Battery Level
The battery level request's type is 1. It requires no data and returns a uint8 in its value field.
Example request:
{"type":1}
Example response:
{"type":1,"value":65,"error":false}
Firmware Version
The firmware version request's type is 2. It requires no data and returns a string in its value field.
Example request:
{"type":2}
Example response:
{"type":2,"value":"1.6.0","error":false}
Firmware Upgrade
The firmware upgrade request's type is 3. It requires data in the following format:
| Field | Type |
|---|---|
| type | int |
| files | []string |
Example requests:
{"type": 3, "data": {"type": 0, "files": ["pinetime-mcuboot-app-dfu-1.6.0.zip"]}}
{"type": 3, "data": {"type": 1, "files": ["pinetime-mcuboot-app-image-1.6.0.bin", "pinetime-mcuboot-app-image-1.6.0.dat"]}}
The paths need to be absolute. They are not absolute here as this is an example.
Example response:
{"type":3,"value":{"sent":2800,"recvd":2800,"total":361152},"error":false}
Responses will be sent continuously until the transfer is complete.
Bluetooth Address
The bluetooth address request's type is 4. It requires no data and returns a string in its value field.
Example request:
{"type":4}
Example response:
{"type":4,"value":"ED:47:AC:47:F4:FB","error":false}
Notify
The notify request's type is 5. It reques data in the following format:
| Field | Type |
|---|---|
| title | string |
| body | string |
Example request:
{"type": 5, "data": {"title": "title1", "body": "body1"}}
Example response:
{"type":5,"error":false}
Set Time
The set time request's type is 6. It requires a string as data. The string must be a date and time formatted as ISO8601/RFC3339 or the string "now".
Example requests:
{"type":6,"data":"2021-10-24T06:40:35-07:00"}
{"type":6,"data":"now"}
Example response:
{"type":6,"error":false}
Watch Heart Rate
The watch heart rate request's type is 7. It requires no data. It returns a uint8 as its value every time the heart rate changes until it is canceled via the cancel request. It also returns an ID for use with the cancel request.
Example request:
{"type":7}
Example response:
{"type":7,"value":83,"id":"d12e2ec2-accd-400c-9da7-be86580b067f","error":false}
Watch Battery Level
The watch battery level request's type is 8. It requires no data. It returns a uint8 as its value every time the battery level changes until it is canceled via the cancel request. It also returns an ID for use with the cancel request.
Example request:
{"type":8}
Example response:
{"type":8,"value":63,"id":"70cce449-d8b8-4e07-a000-0ca4ee7a9c42","error":false}
Motion
The motion request's type is 9. It requires no data. It returns data in the following format:
| Field | Type |
|---|---|
| X | int16 |
| Y | int16 |
| Z | int16 |
The values will only update if the watch is not sleeping.
Example request:
{"type":9}
Example response:
{"type":9,"value":{"X":-220,"Y":475,"Z":-893},"error":false}
Watch Motion
The watch motion request's type is 10. It requires no data. It returns the same data as the motion request as its value every time the watch moves until it is canceled via the cancel request. It also returns an ID for use with the cancel request.
Example request:
{"type":10}
Example response:
{"type":10,"value":{"X":-220,"Y":475,"Z":-893},"id":"d084789d-9fdc-4fce-878b-4408cd616901","error":false}
Step Count
The step count request's type is 11. It requires no data and returns a uint32 in its value field.
Example request:
{"type":11}
Example response:
{"type":11,"value":1043,"error":false}
Watch Step Count
The watch step count request's type is 12. It requires no data. It returns a uint32 in its value field every time the step count changes until it is canceled via the cancel request. It also returns an ID for use with the cancel request.
Example request:
{"type":12}
Example response:
{"type":12,"value":1045,"id":"54583e8f-80f6-45e3-a97f-b111defc0edc","error":false}
Cancel
The cancel request's type is 13. It requires a string as data, containing the ID returned by a watch request. Once run, it will terminate the watch request, clean up anything it was using, and cause ITD to stop listening for its value from the watch.
Example request:
{"type":13,"data":"54583e8f-80f6-45e3-a97f-b111defc0edc"}
Example response:
{"type":13,"error":false}