Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

unofficial-sense

1.1.4 • Public • Published

Unofficial Sense API for NodeJS

This is an UNOFFICIAL implimentation of the Sense Home Energy Monitoring API using es6 and promises with real time support.

This has also been integrated into a node-red module, see it here.

Installation

npm install unofficial-sense

Usage

const sense = require('unofficial-sense')
 
sense({
    email: "email",
    password: "password plain text or base64"
}, (data) => {
    console.log(data) 
    //real time data stream from your sense monitor
})

The callback (optional) will be called anytime data updates from the Sense websocket. There are two status types that will be returned in this callback

Authenticated

{
    "status": "Authenticated",
    "data": { 
        "authorized": true,
        "account_id": "xxxxx",
        "user_id": "xxxxx",
        "access_token": "token",
        "monitors":
        [ { "id": "xxxxx",
            "time_zone": "America/Los_Angeles",
            "solar_connected": false,
            "solar_configured": false,
            "online": false,
            "attributes": [Object],
            "signal_check_completed_time": "2017-10-17T23:51:23.000Z" } ],
        "bridge_server": "wss://mb1.home.sense.com",
        "partner_id": null,
        "date_created": "2017-10-17T23:52:37.000Z"
    }
}

Recevied

{
    "status": "Received",
    "data": {
    "type": "realtime_update",
    "payload": {
        "hz": 60.003795623779,
        "c": 122,
        "channels": [
        5870.3833007812,
        5293.4794921875
        ],
        "devices": [
        {
            "c": 61,
            "w": 5584.701171875,
            "name": "Dryer",
            "icon": "washer",
            "id": "11654c89",
            "tags": {
            "AlwaysOn": "false",
            "UserEditable": "true",
            "DateFirstUsage": "2017-10-19",
            "name_useredit": "false",
            "OriginalName": "Dryer",
            "DeviceListAllowed": "true",
            "DefaultUserDeviceType": "Dryer",
            "TimelineAllowed": "true",
            "Type": "ElectricDryer",
            "UserDeviceType": "Dryer",
            "DeployToMonitor": "true",
            "Revoked": "false",
            "PeerNames": [
                {
                "UserDeviceType": "Dryer",
                "Percent": 97,
                "UserDeviceTypeDisplayString": "Dryer",
                "Icon": "washer",
                "Name": "Dryer"
                },
                {
                "UserDeviceType": "Washer",
                "Percent": 1,
                "UserDeviceTypeDisplayString": "Washer",
                "Icon": "dishes",
                "Name": "Washer"
                },
                {
                "UserDeviceType": "StoveTop",
                "Percent": 1,
                "UserDeviceTypeDisplayString": "Stove Top",
                "Icon": "stove",
                "Name": "Stove"
                },
                {
                "UserDeviceType": "WaterHeater",
                "Percent": 1,
                "UserDeviceTypeDisplayString": "Water Heater",
                "Icon": "heat",
                "Name": "Water heater"
                }
            ],
            "PreselectionIndex": 0,
            "UserDeviceTypeDisplayString": "Dryer",
            "Mature": "true",
            "Alertable": "true",
            "ModelCreatedVersion": "10",
            "TimelineDefault": "true",
            "Pending": "false",
            "user_editable": "true"
            }
        },
        {
            "c": 47,
            "w": 4340.5068359375,
            "name": "Other",
            "icon": "home",
            "id": "unknown",
            "tags": {
            "DefaultUserDeviceType": "Unknown",
            "TimelineAllowed": "false",
            "UserDeviceType": "Unknown",
            "UserEditable": "false",
            "UserDeviceTypeDisplayString": "Unknown",
            "DeviceListAllowed": "true",
            "user_editable": "false"
            }
        },
        {
            "c": 7,
            "w": 726,
            "name": "Always On",
            "icon": "alwayson",
            "id": "always_on",
            "tags": {
            "DefaultUserDeviceType": "AlwaysOn",
            "TimelineAllowed": "false",
            "UserDeviceType": "AlwaysOn",
            "UserEditable": "false",
            "UserDeviceTypeDisplayString": "AlwaysOn",
            "DeviceListAllowed": "true",
            "user_editable": "false"
            }
        },
        {
            "c": 5,
            "w": 512.65478515625,
            "name": "Washer",
            "icon": "dishes",
            "id": "ccd27606",
            "tags": {
            "AlwaysOn": "false",
            "UserEditable": "true",
            "DateFirstUsage": "2017-10-19",
            "name_useredit": "false",
            "OriginalName": "Washer",
            "DeviceListAllowed": "true",
            "DefaultUserDeviceType": "Washer",
            "TimelineAllowed": "true",
            "Type": "WashingMachine",
            "UserDeviceType": "Washer",
            "DeployToMonitor": "true",
            "Revoked": "false",
            "PeerNames": [
                {
                "UserDeviceType": "Washer",
                "Percent": 96,
                "UserDeviceTypeDisplayString": "Washer",
                "Icon": "dishes",
                "Name": "Washer"
                }
            ],
            "PreselectionIndex": 0,
            "UserDeviceTypeDisplayString": "Washer",
            "Mature": "true",
            "Alertable": "true",
            "ModelCreatedVersion": "8",
            "TimelineDefault": "true",
            "Pending": "false",
            "user_editable": "true"
            }
        }
        ],
        "w": 11163.86328125,
        "_stats": {
        "mrcv": 1528234116.29,
        "brcv": 1528234116.1969,
        "msnd": 1528234116.29
        },
        "epoch": 1528234102,
        "deltas": [
        
        ],
        "voltage": [
        121.58633422852,
        122.09526824951
        ],
        "frame": 18657330
    }
    }
}

Manual Data Retreival

To get more information, you may need to access the following functions exposed by the promise resolver of the sense function.

  • events.on('data')
  • getDevices
  • getMonitorInfo
  • getTimeline

Using These functions

(Don't forget to pass email/password object)

sense({...}).then((mySense) => {
    mySense.getDevices().then(devices => {
        console.log(devices);
    })
    mySense.getMonitorInfo().then(monitor => {
        console.log(monitor);
    })
    mySense.getTimeline().then(timeline => {
        console.log(timeline);
    })
    mySense.events.on('data', (data) => {
      console.log(data);
    })
})

Or you can try the following

(async () => {
    const mySense = await sense({...})
    const deviceInfo = await mySense.getDevices()
    const monitorInfo = await mySense.getMonitorInfo()
    const timeline = await mySense.getTimeline()
    mySense.events.on('data', (data) => {
      console.log(data);
    })
})

All functions return promises containing the following data

events.on('data')

Use this to subscribe to realtime updates (see above for data example), use this instead of the callback function.

getDevices()

This will retreive all learned devices and the data on those devices with the following format

[
    {
      "id": "xxxxxxx",
      "name": "Microwave",
      "icon": "microwave",
      "tags": {
        "Alertable": "true",
        "AlwaysOn": "false",
        "DateFirstUsage": "2017-10-18",
        "DefaultUserDeviceType": "Microwave",
        "DeployToMonitor": "true",
        "DeviceListAllowed": "true",
        "Mature": "true",
        "ModelCreatedVersion": "10",
        "name_useredit": "false",
        "OriginalName": "Microwave",
        "PeerNames": [
          {
            "Name": "Microwave",
            "UserDeviceType": "Microwave",
            "Percent": 100,
            "Icon": "microwave",
            "UserDeviceTypeDisplayString": "Microwave"
          }
        ],
        "Pending": "false",
        "PreselectionIndex": 0,
        "Revoked": "false",
        "TimelineAllowed": "true",
        "TimelineDefault": "true",
        "Type": "Microwave",
        "user_editable": "true",
        "UserDeviceTypeDisplayString": "Microwave",
        "UserEditable": "true"
      }
    },
    {
      "id": "xxxxxxx",
      "name": "Stove 2",
      "icon": "stove",
      "tags": {
        "Alertable": "true",
        "AlwaysOn": "false",
        "DateFirstUsage": "2017-10-19",
        "DefaultUserDeviceType": "StoveTop",
        "DeployToMonitor": "true",
        "DeviceListAllowed": "false",
        "Mature": "true",
        "ModelCreatedVersion": "12",
        "name_useredit": "false",
        "OriginalName": "Stove 2",
        "PeerNames": [
          {
            "Name": "Stove",
            "UserDeviceType": "StoveTop",
            "Percent": 9000,
            "Icon": "stove",
            "UserDeviceTypeDisplayString": "Stove Top"
          }
        ],
        "Pending": "false",
        "PreselectionIndex": 0,
        "Revoked": "true",
        "TimelineAllowed": "false",
        "TimelineDefault": "true",
        "Type": "Stove",
        "user_editable": "false",
        "UserDeviceTypeDisplayString": "Stove Top",
        "UserEditable": "false"
      }
    },
    {
      "id": "xxxxxxxx",
      "name": "Washer",
      "icon": "dishes",
      "tags": {
        "Alertable": "true",
        "AlwaysOn": "false",
        "DateFirstUsage": "2017-10-19",
        "DefaultUserDeviceType": "Washer",
        "DeployToMonitor": "true",
        "DeviceListAllowed": "true",
        "Mature": "true",
        "ModelCreatedVersion": "8",
        "name_useredit": "false",
        "OriginalName": "Washer",
        "PeerNames": [
          {
            "Name": "Washer",
            "UserDeviceType": "Washer",
            "Percent": 96,
            "Icon": "dishes",
            "UserDeviceTypeDisplayString": "Washer"
          }
        ],
        "Pending": "false",
        "PreselectionIndex": 0,
        "Revoked": "false",
        "TimelineAllowed": "true",
        "TimelineDefault": "true",
        "Type": "WashingMachine",
        "user_editable": "true",
        "UserDeviceTypeDisplayString": "Washer",
        "UserEditable": "true"
      }
    } 
]

getMonitorInfo()

{
  "signals": {
    "progress": 100,
    "status": "OK"
  },
  "device_detection": {
    "in_progress": [
      {
        "icon": "cup",
        "name": "Possible Coffee Maker",
        "progress": 16
      },
      {
        "icon": "dishes",
        "name": "Possible Dishwasher",
        "progress": 5
      },
      {
        "icon": "stove",
        "name": "Possible Oven",
        "progress": 10
      } 
    ],
    "found": [
      {
        "icon": "stove",
        "name": "Oven",
        "progress": 48
      },
      {
        "icon": "dishes",
        "name": "Washer",
        "progress": 50
      },
      {
        "icon": "home",
        "name": "Motor",
        "progress": 96
      }
    ],
    "num_detected": 18
  },
  "monitor_info": {
    "serial": "XXXXXXXXXX",
    "ndt_enabled": true,
    "online": true,
    "version": "1.11.1870-2d186a5-master",
    "ssid": "For the Horde",
    "signal": "-44 dBm",
    "mac": "xx:xx:xx:xx:xx:xx"
  }
}

getTimeline()

{
  "more_items": true,
  "sticky_items": [
    {
      "time": "2018-06-01T05:56:24.350Z",
      "type": "Info",
      "subtype": "NewDeviceFound",
      "icon": "heat",
      "body": "Sense found a new device and named it 'Heat 3'.",
      "destination": "device:fbcff7e5",
      "device_id": "fbcff7e5",
      "device_name": "Heat 3",
      "show_action": false,
      "allow_sticky": true,
      "guid": "f733cb4f-5250-479b-8fc6-64d2dc6baedc",
      "user_device_type": "MysteryHeat"
    },
    {
      "time": "2018-06-01T05:56:24.215Z",
      "type": "Info",
      "subtype": "NewDeviceFound",
      "icon": "settings",
      "body": "Sense found a new device and named it 'Motor 2'.",
      "destination": "device:cad5432c",
      "device_id": "cad5432c",
      "device_name": "Motor 2",
      "show_action": false,
      "allow_sticky": true,
      "guid": "dc21dd5f-1211-4e34-9766-ecd2d1944727",
      "user_device_type": "MysteryMotor"
    }
  ],
  "user_id": xxxxx,
  "items": [
    {
      "time": "2018-06-05T21:57:43.086Z",
      "type": "DeviceOn",
      "icon": "heat",
      "body": "{device.name} turned on",
      "destination": "device:qtdquGC6",
      "device_id": "qtdquGC6",
      "device_name": "Heat 4",
      "show_action": false,
      "allow_sticky": false,
      "guid": "b4ac6c21-2767-48b7-97f3-abe0dca1d0d2",
      "user_device_type": "MysteryHeat"
    },
    {
      "time": "2018-06-05T21:57:18.669Z",
      "type": "DeviceOn",
      "icon": "stove",
      "body": "{device.name} turned on",
      "destination": "device:6aa95d8f",
      "device_id": "6aa95d8f",
      "device_name": "Rear left burner",
      "show_action": false,
      "allow_sticky": false,
      "guid": "63952534-e661-480c-8d67-e54badd809cb",
      "user_device_type": "Oven"
    },
    {
      "time": "2018-06-05T21:46:04.276Z",
      "type": "DeviceWasOn",
      "icon": "heat",
      "body": "{device.name} was on for 7 minutes",
      "destination": "device:bdee9e9a",
      "start_time": "2018-06-05T21:38:43.452Z",
      "device_id": "bdee9e9a",
      "device_name": "Water heater",
      "show_action": false,
      "children": [
        {
          "time": "2018-06-05T21:46:04.276Z",
          "type": "DeviceOff",
          "icon": "heat",
          "body": "{device.name} turned off",
          "destination": "device:bdee9e9a",
          "device_id": "bdee9e9a",
          "device_name": "Water heater",
          "show_action": false,
          "allow_sticky": false,
          "location": "Laundry room",
          "guid": "e6173b29-995b-4d20-b7d7-5c3f6d329bd6",
          "user_device_type": "WaterHeater"
        },
        {
          "time": "2018-06-05T21:38:43.452Z",
          "type": "DeviceOn",
          "icon": "heat",
          "body": "{device.name} turned on",
          "destination": "device:bdee9e9a",
          "device_id": "bdee9e9a",
          "device_name": "Water heater",
          "show_action": false,
          "allow_sticky": false,
          "location": "Laundry room",
          "guid": "9bdcadf3-cde7-4803-9a34-9948dca37e10",
          "user_device_type": "WaterHeater"
        }
      ],
      "allow_sticky": false,
      "location": "Laundry room",
      "guid": "9bdcadf3-cde7-4803-9a34-9948dca37e10",
      "user_device_type": "WaterHeater"
    },
    {
      "time": "2018-06-05T21:26:35.914Z",
      "type": "DeviceOff",
      "icon": "heat",
      "body": "{device.name} turned off",
      "destination": "device:gea4Jysu",
      "device_id": "gea4Jysu",
      "device_name": "Baby Bottle Warmer",
      "show_action": false,
      "allow_sticky": false,
      "location": "Bathroom",
      "guid": "49c415cc-abc5-4f7f-b01f-3d8ba0408548",
      "user_device_type": "MysteryHeat"
    },
    {
      "time": "2018-06-05T21:25:06.805Z",
      "type": "DeviceOn",
      "icon": "dishes",
      "body": "{device.name} turned on",
      "destination": "device:ccd27606",
      "device_id": "ccd27606",
      "device_name": "Washer",
      "show_action": false,
      "allow_sticky": false,
      "guid": "88cc8138-1779-40af-be2e-4d3da341319e",
      "user_device_type": "Washer"
    },
    {
      "time": "2018-06-05T21:21:11.167Z",
      "type": "DeviceOn",
      "icon": "washer",
      "body": "{device.name} turned on",
      "destination": "device:11654c89",
      "device_id": "11654c89",
      "device_name": "Dryer",
      "show_action": false,
      "allow_sticky": false,
      "guid": "725f6c18-05f5-422c-b562-eb439501015c",
      "user_device_type": "Dryer"
    },
    {
      "time": "2018-06-05T21:11:37.193Z",
      "type": "DeviceOn",
      "icon": "heat",
      "body": "{device.name} turned on",
      "destination": "device:gea4Jysu",
      "device_id": "gea4Jysu",
      "device_name": "Baby Bottle Warmer",
      "show_action": false,
      "allow_sticky": false,
      "location": "Bathroom",
      "guid": "b7c01d78-5276-41ea-9413-cdbac06e5647",
      "user_device_type": "MysteryHeat"
    } 
  ]
}

Disclaimer

This module was developed without the consent of the Sense company, and makes use of an undocumented and unsupported API. Use at your own risk, and be aware that Sense may change the API at any time and break this repository perminantly.

Install

npm i unofficial-sense

DownloadsWeekly Downloads

3

Version

1.1.4

License

MIT

Unpacked Size

22.1 kB

Total Files

4

Last publish

Collaborators

  • avatar