Items
Version 0.7
This API is under active development. Changes will result in a new version to maintain backward compatibility.
All timestamps are stored in GMT, so they will need converted to local time by the client. This is to prevent overlaps in the data due to Daylight Savings Time.
Data is returned in descending order.
Views
Changes
-
v0.4
-
Changed from ‘devices’ to ‘items’
-
v0.2
- Added NYCE sensors
- Timeseries data is returned in descending order by stamp
-
v0.1
- First version
MedTracker
The MedTracker device tracks when users open and close doors on a 7 day pill box. The door states are timestamped and stored locally until cleared by another device. The MedTracker can hold up to a months worth of data before the circular buffer starts overwritting the oldest door states. A new state is recorded each time there is a up or down door change detected.
When plugged into a wall outlet the MedTracker can be polled at anytime. On batteries it will only power its bluetooth hardware at the next_panic_start time. This value is present when the status is requested from the MedTracker.
When requested, the medtracker will send a status report indicating important information about the device such as the battery life, firmware, time, etc. It will also send the collected door states. These door states are stored as a timestamped bitmask where sunday starts at 1 instead of 0. Below is an example table showing event data.
Event | Door States (U is open,- is closed) | Calculation | Description |
---|---|---|---|
0 | - - - - - - - | 0 | All doors are closed |
1 | U - - - - - - | 2^0 | Door at position 0 (Sunday) is open |
2 | - U - - - - - | 2^1 | Door at position 1 (Monday) is open |
3 | U U - - - - - | 2^0 + 2^1 | Door at positions 0 & 1 (Sunday & Monday ) are open |
4 | - - U - - - - | 2^2 | Door at position 2 (Tuesday) is open |
5 | U - U - - - - | 2^0 + 2^2 | Door at position 0 & 2 (Sunday and Tuesday) are open |
6 | - U U - - - - | 2^1 + 2^2 | Door at positions 1 & 2 (Monday and Tuesday) are open |
7 | U U U - - - - | 2^0 + 2^1 + 2^2 | Door at positions 0 & 1 & 2 (Sunday - Tuesday) are open |
When determining when someone is taking a pill it is important to compare the inital state of the door to the current state of the door. For example, both a change from an open state to a closed or a closed to an open state may indicate that a pill was taken.
We have seen people use the pill box in a variety of ways, from leaving all of the doors open and only closing when they have taken the pill to leaving the door open after taking the pill and only closing them when reloading the pill box.
A simplistic approach to determine when the user is reloading as opposed to taking a pill is to look for greater than 6 door events within a ten minute period.
When used with ORCATECH’s PlugPC, the PlugPC will poll the medtracker device once an hour. The status and door states are read from the MedTracker and recorded locally. Data stored on the PlugPC is then transmitted back to the ORCATECH servers once a day at night.
Installation
-
Plug in the MedTracker.
- A green LED will light up where the cord goes into the box to indicate a power draw.
-
Turn on the MedTracker
- There is a switch on the inside of the box. Using a paper clip, you can switch it through a small hole on the back.
- When the MedTracker is on, a red LED will light up on the back of the box.
Specifications
Name | Value |
---|---|
Batteries | #2 9 volt |
Communication | Bluetooth Classic |
NYCE
The NYCE sensors are Zigbee devices created by the NYCE Control company which adhere to the Zigbee HA 1.2 specification. There are three types of NYCE sensors currently in use by ORCATECH: wall, door/window, and curtain sensor. Each sensor detects events and sends a bitmask representing it’s state when each event happens (see page 337 of zigbee spec). It will also send a heartbeat of it’s state every 2 hours.The nyce specifications can be found here.
Wall Sensor
This is an IR sensor that detects presence. When presence is detected it will send it's state to the hub and is timestamped upon arrival. After 5 seconds it will wait until it does not detect a presence and send another state to the hub. In the Zigbee protocol, alarm 2 indicates presence.Door/Windows Sensor
This sensor is composed of two pieces: a magnet and a detector. It will send it's state when the magnet comes within range and when it leaves. The data is timestamped upon arrive at the hub. In the Zigbee protocol, alarm 1 indications proximity.Curtain Sensor
The curtain sensor is the wall sensor with a restricted covering over the lens for the sensor. These sensors are installed in a line for detection of walking speed.Installation
-
Setup ORCATECH Hub
-
Plug in the Telegisis Zigbee dongle
-
Join the sensor to the PAN
- Go to the Hub’s Control Panel
- Go to Setup->SensorPlacement
- Click on the top left menu and add the sensor to the map
- Click on the sensor -> Join Pan
- Remove cover on sensor and press the button near the battery 10 times.
Specifications
Name | Value |
---|---|
Batteries | CR2 |
Communication | Zigbee, HA1.2 Compliant |
MedTracker Data ¶
Status ¶
Retrieves the status history for a particular MedTracker item specified by itemname.
If the request has required parameter that is malformed than the service will response with a 422 HTTP error code.
If the item name can not be found then the server with send a 404 response.
If the request is made without the Authorization header, the authorization token has expired or the token is invalid, then the server with respond with a 401 response.
All requests will be sending JSON back to the client, therefore the client will need to include an Accept header with the request indicating that it will accept json responses. If the Accept header is missing or malformed in the request a 400 HTTP error code will be returned. The Accept header should look like the following:
Accept: application/json
StatusGET/medtrackers/{itemname}/status{?skip,limit,before}
Example URI
- itemname
string
(required) Example: MT0301Device item name returned by GET request to devices/medtrackers
- skip
integer
(optional) Default: 0 Example: 0The number of devices to skip
- limit
integer
(optional) Default: 1000 Example: 25The maximum number of devices to return, up to
1000
- before
integer
(optional) Default: '1136073600' Example: 1466536128Return status with a stamp less than this unix timestamp, default to the current timestamp
200
Headers
ContentType: application/json
Body
[
{
"stamp": 1433592610,
"devicestamp": 1466107302,
"voltage": 1023,
"powersource": "external_power",
"eventcount": 32,
"batteryseconds": "4",
"firmwarerevsion": "mt9a28.c",
"macaddress": "00:A0:96:14:18:5B",
"nextpanicstart": 1457413200,
"nextpanicstop": 1457413500
}
]
Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"stamp": {
"type": "number",
"description": "Time in which the status was polled as a unix timestamp"
},
"devicestamp": {
"type": "number",
"description": "Current time as reported by the device as a unix timestamp"
},
"voltage": {
"type": "number",
"description": "Device voltage"
},
"powersource": {
"type": "string",
"description": "Description of current power source. Either external_power or battery"
},
"eventcount": {
"type": "number",
"description": "Total number of door states recorded by the medtracker"
},
"batteryseconds": {
"type": "string",
"description": "Seconds spent using the battery as the power source"
},
"firmwarerevsion": {
"type": "string",
"description": "Firmware version of the hardware"
},
"macaddress": {
"type": "string",
"description": "Reported mac address of the MedTracker"
},
"nextpanicstart": {
"type": "number",
"description": "Start time of next blueooth broadcast as a unix timestamp"
},
"nextpanicstop": {
"type": "number",
"description": "Stop time of next bluetooth broadcast as a unix timestamp"
}
},
"required": [
"stamp",
"devicestamp",
"voltage",
"powersource",
"eventcount",
"batteryseconds",
"firmwarerevsion",
"macaddress",
"nextpanicstart",
"nextpanicstop"
]
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
400
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
401
Headers
Content-Type: application/json
WWW-Authenticate: OAuth2.0 realm=juno.orcatech.org, error=invalid_token, error_description=descriptive string
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
404
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
422
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
Events ¶
Retrieves the event history for a particular MedTracker item specified by itemname.
If the request has required parameter that is malformed than the service will response with a 422 HTTP error code.
If the item name can not be found then the server with send a 404 response.
If the request is made without the Authorization header, the authorization token has expired or the token is invalid, then the server with respond with a 401 response.
All requests will be sending JSON back to the client, therefore the client will need to include an Accept header with the request indicating that it will accept json responses. If the Accept header is missing or malformed in the request a 400 HTTP error code will be returned. The Accept header should look like the following:
Accept: application/json
EventsGET/medtrackers/{itemname}/events{?skip,limit,before}
Example URI
- itemname
string
(required) Example: MT0301Device item name returned by GET request to devices/medtrackers
- skip
integer
(optional) Default: 0 Example: 0The number of devices to skip
- limit
integer
(optional) Default: 1000 Example: 25The maximum number of devices to return, up to
1000
- before
integer
(optional) Default: '1136073600' Example: 1466536128Return events stamped before this unix timestamp, defaults to current timestamp
200
Headers
ContentType: application/json
Body
[
{
"stamp": 1466372658,
"event": 4
}
]
Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"stamp": {
"type": "number",
"description": "Time in which the event occured as a unix timestamp"
},
"event": {
"type": "number",
"description": "Represents the state of the MedTracker doors as a bitmask where position 0 is Sunday and 6 is Saturday"
}
},
"required": [
"stamp",
"event"
]
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
400
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
401
Headers
Content-Type: application/json
WWW-Authenticate: OAuth2.0 realm=juno.orcatech.org, error=invalid_token, error_description=descriptive string
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
404
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
422
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
NYCE Data ¶
Events ¶
Retrieves the event history for a particular NYCE item specified by itemname.
If the request has required parameter that is malformed than the service will response with a 422 HTTP error code.
If the item name can not be found then the server with send a 404 response.
If the request is made without the Authorization header, the authorization token has expired or the token is invalid, then the server with respond with a 401 response.
All requests will be sending JSON back to the client, therefore the client will need to include an Accept header with the request indicating that it will accept json responses. If the Accept header is missing or malformed in the request a 400 HTTP error code will be returned. The Accept header should look like the following:
Accept: application/json
EventsGET/nyce/{itemname}/events{?skip,limit,before}
Example URI
- itemname
string
(required) Example: nyce-w-0010Device item name returned by GET request to devices/nyce
- skip
integer
(optional) Default: 0 Example: 0The number of devices to skip
- limit
integer
(optional) Default: 1000 Example: 25The maximum number of devices to return, up to
1000
- before
integer
(optional) Default: '1466536128' Example: 1466536128Return events stamped before this unix timestamp, defaults to current timestamp
200
Headers
ContentType: application/json
Body
[
{
"stamp": 1466372658,
"event": 48
}
]
Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"stamp": {
"type": "number",
"description": "Time in which the event occured as a unix timestamp"
},
"event": {
"type": "number",
"description": "Bitmask representing the current state of the NYCE sensor as outlined in the <a href=\"https://juno.orcatech.org/apis/orcatech/v0.2/docs/images/zigbee_ha.pdf\">Zigbee HA specification</a> page 337"
}
},
"required": [
"stamp",
"event"
]
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
400
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
401
Headers
Content-Type: application/json
WWW-Authenticate: OAuth2.0 realm=juno.orcatech.org, error=invalid_token, error_description=descriptive string
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
404
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}
422
Headers
Content-Type: application/json
Body
{
"code": 0,
"message": "Unknown error"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "Numeric code of the error that occured"
},
"message": {
"type": "string",
"description": "Description of the error code"
}
},
"required": [
"code",
"message"
]
}