Back to top

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

MedTracker Image

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

  1. Plug in the MedTracker.

    • A green LED will light up where the cord goes into the box to indicate a power draw.
  2. 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

NYCE 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

NYCE Door 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

NYCE 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

  1. Setup ORCATECH Hub

  2. Plug in the Telegisis Zigbee dongle

  3. 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

Status
GET/medtrackers/{itemname}/status{?skip,limit,before}

Example URI

GET https://juno.orcatech.org/apis/orcatech/v0.4/items/medtrackers/MT0301/status?skip=0&limit=25&before=1466536128
URI Parameters
HideShow
itemname
string (required) Example: MT0301

Device item name returned by GET request to devices/medtrackers

skip
integer (optional) Default: 0 Example: 0

The number of devices to skip

limit
integer (optional) Default: 1000 Example: 25

The maximum number of devices to return, up to 1000

before
integer (optional) Default: '1136073600' Example: 1466536128

Return status with a stamp less than this unix timestamp, default to the current timestamp

Response  200
HideShow
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#"
}
Response  400
HideShow
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"
  ]
}
Response  401
HideShow
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"
  ]
}
Response  404
HideShow
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"
  ]
}
Response  422
HideShow
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

Events
GET/medtrackers/{itemname}/events{?skip,limit,before}

Example URI

GET https://juno.orcatech.org/apis/orcatech/v0.4/items/medtrackers/MT0301/events?skip=0&limit=25&before=1466536128
URI Parameters
HideShow
itemname
string (required) Example: MT0301

Device item name returned by GET request to devices/medtrackers

skip
integer (optional) Default: 0 Example: 0

The number of devices to skip

limit
integer (optional) Default: 1000 Example: 25

The maximum number of devices to return, up to 1000

before
integer (optional) Default: '1136073600' Example: 1466536128

Return events stamped before this unix timestamp, defaults to current timestamp

Response  200
HideShow
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#"
}
Response  400
HideShow
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"
  ]
}
Response  401
HideShow
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"
  ]
}
Response  404
HideShow
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"
  ]
}
Response  422
HideShow
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

Events
GET/nyce/{itemname}/events{?skip,limit,before}

Example URI

GET https://juno.orcatech.org/apis/orcatech/v0.4/items/nyce/nyce-w-0010/events?skip=0&limit=25&before=1466536128
URI Parameters
HideShow
itemname
string (required) Example: nyce-w-0010

Device item name returned by GET request to devices/nyce

skip
integer (optional) Default: 0 Example: 0

The number of devices to skip

limit
integer (optional) Default: 1000 Example: 25

The maximum number of devices to return, up to 1000

before
integer (optional) Default: '1466536128' Example: 1466536128

Return events stamped before this unix timestamp, defaults to current timestamp

Response  200
HideShow
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#"
}
Response  400
HideShow
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"
  ]
}
Response  401
HideShow
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"
  ]
}
Response  404
HideShow
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"
  ]
}
Response  422
HideShow
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"
  ]
}