karbassi/netatmo

A node.js module to hook into the netatmo API.

netatmo

A node.js module to interface with the netatmo api API.

Getting Starting

1. Make sure you have a netatmo account.
2. Make sure you have at least one netatmo device set up.

Install

npm install netatmo

Example #1

var netatmo = require('netatmo');

var auth = {
  "client_id": "",
  "client_secret": "",
  "username": "",
  "password": "",
};

var api = new netatmo(auth);

// Get Stations Data
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/weatherstation/getstationsdata
api.getStationsData(function(err, devices) {
  console.log(devices);
});

// Get Measure
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/common/getmeasure
var options = {
  device_id: '',
  scale: 'max',
  type: ['Temperature', 'CO2', 'Humidity', 'Pressure', 'Noise'],
};

api.getMeasure(options, function(err, measure) {
  console.log(measure.length);
  console.log(measure[0]);
});


// Set Sync Schedule
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/thermostat/syncschedule
var options = {
  device_id: '',
  module_id: '',
  zones: [
    { type: 0, id: 0, temp: 19 },
    { type: 1, id: 1, temp: 17 },
    { type: 2, id: 2, temp: 12 },
    { type: 3, id: 3, temp: 7 },
    { type: 5, id: 4, temp: 16 }
  ],
  timetable: [
    { m_offset: 0, id: 1 },
    { m_offset: 420, id: 0 },
    { m_offset: 480, id: 4 },
    { m_offset: 1140, id: 0 },
    { m_offset: 1320, id: 1 },
    { m_offset: 1860, id: 0 },
    { m_offset: 1920, id: 4 },
    { m_offset: 2580, id: 0 },
    { m_offset: 2760, id: 1 },
    { m_offset: 3300, id: 0 },
    { m_offset: 3360, id: 4 },
    { m_offset: 4020, id: 0 },
    { m_offset: 4200, id: 1 },
    { m_offset: 4740, id: 0 },
    { m_offset: 4800, id: 4 },
    { m_offset: 5460, id: 0 },
    { m_offset: 5640, id: 1 },
    { m_offset: 6180, id: 0 },
    { m_offset: 6240, id: 4 },
    { m_offset: 6900, id: 0 },
    { m_offset: 7080, id: 1 },
    { m_offset: 7620, id: 0 },
    { m_offset: 8520, id: 1 },
    { m_offset: 9060, id: 0 },
    { m_offset: 9960, id: 1 }
  ],
};

api.setSyncSchedule(options, function(err, status) {
  console.log(status);
});


// Set Thermpoint
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/thermostat/setthermpoint
var options = {
  device_id: '',
  module_id: '',
  setpoint_mode: '',
};

api.setThermpoint(options, function(err, status) {
  console.log(status);
});

Example #2

var netatmo = require('netatmo');

var auth = {
  "client_id": "",
  "client_secret": "",
  "username": "",
  "password": "",
};

var api = new netatmo(auth);

var getStationsData = function(err, devices) {
  console.log(devices);
};

var getMeasure = function(err, measure) {
  console.log(measure.length);
  console.log(measure[0]);
};

var getThermostatsData = function(err, devices) {
  console.log(devices);
};

var setSyncSchedule = function(err, status) {
  console.log(status);
};

var setThermpoint = function(err, status) {
  console.log(status);
};

var getHomeData = function(err, data) {
  console.log(data);
};

var handleEvents = function(err, data) {
  console.log(data.events_list);
};


// Event Listeners
api.on('get-stationsdata', getStationsData);
api.on('get-measure', getMeasure);
api.on('get-thermostatsdata', getThermostatsData);
api.on('set-syncschedule', setSyncSchedule);
api.on('set-thermpoint', setThermpoint);
api.on('get-homedata', getHomeData);
api.on('get-nextevents', handleEvents);
api.on('get-lasteventof', handleEvents);
api.on('get-eventsuntil', handleEvents);

// Get Stations Data
// See docs: https://dev.netatmo.com/doc/methods/getstationsdata
api.getStationsData();

// Get Measure
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/common/getmeasure
var options = {
  device_id: '',
  scale: 'max',
  type: ['Temperature', 'CO2', 'Humidity', 'Pressure', 'Noise'],
};

api.getMeasure(options);

// Get Thermostats Data
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/thermostat/getthermostatsdata
var options = {
  device_id: '',
};

api.getThermostatsData(options);

// Set Sync Schedule
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/thermostat/syncschedule
var options = {
  device_id: '',
  module_id: '',
  zones: [
    { type: 0, id: 0, temp: 19 },
    { type: 1, id: 1, temp: 17 },
    { type: 2, id: 2, temp: 12 },
    { type: 3, id: 3, temp: 7 },
    { type: 5, id: 4, temp: 16 }
  ],
  timetable: [
    { m_offset: 0, id: 1 },
    { m_offset: 420, id: 0 },
    { m_offset: 480, id: 4 },
    { m_offset: 1140, id: 0 },
    { m_offset: 1320, id: 1 },
    { m_offset: 1860, id: 0 },
    { m_offset: 1920, id: 4 },
    { m_offset: 2580, id: 0 },
    { m_offset: 2760, id: 1 },
    { m_offset: 3300, id: 0 },
    { m_offset: 3360, id: 4 },
    { m_offset: 4020, id: 0 },
    { m_offset: 4200, id: 1 },
    { m_offset: 4740, id: 0 },
    { m_offset: 4800, id: 4 },
    { m_offset: 5460, id: 0 },
    { m_offset: 5640, id: 1 },
    { m_offset: 6180, id: 0 },
    { m_offset: 6240, id: 4 },
    { m_offset: 6900, id: 0 },
    { m_offset: 7080, id: 1 },
    { m_offset: 7620, id: 0 },
    { m_offset: 8520, id: 1 },
    { m_offset: 9060, id: 0 },
    { m_offset: 9960, id: 1 }
  ],
};

api.setSyncSchedule(options);

// Set Thermstate
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/thermostat/setthermpoint
var options = {
  device_id: '',
  module_id: '',
  setpoint_mode: '',
};

api.setThermpoint(options);

// Get Home Data
// https://dev.netatmo.com/dev/resources/technical/reference/cameras/gethomedata
api.getHomeData();

// Get Next Events
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/cameras/getnextevents
var options = {
  home_id: '',
  event_id: ''
};

api.getNextEvents(options);

// Get Last Event Of
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/cameras/getlasteventof
var options = {
  home_id: '',
  person_id: ''
};

api.getLastEventOf(options);

// Get Events Until
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/cameras/geteventsuntil
var options = {
  home_id: '',
  event_id: ''
};

api.getEventsUntil(options);

// Get Camera Picture
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/cameras/getcamerapicture
var options = {
  image_id: '',
  key: ''
};

api.getCameraPicture(options);

Catching Errors and Warnings

var netatmo = require('netatmo');

var auth = {
  "client_id": "",
  "client_secret": "",
  "username": "",
  "password": "",
};

var api = new netatmo(auth);

api.on("error", function(error) {
    // When the "error" event is emitted, this is called
    console.error('Netatmo threw an error: ' + error);
});

api.on("warning", function(error) {
    // When the "warning" event is emitted, this is called
    console.log('Netatmo threw a warning: ' + error);
});

// Rest of program

License

MIT © Ali Karbassi

netatmo's Issues

Add "synchomeschedule" API

Tech docs: https://dev.netatmo.com/resources/technical/reference/energy/synchomeschedule

Handling errors when requests can’t be fulfilled

Hello @karbassi, @Nibbler999

I have small issue using the library in a continuously running application. Sometimes, for whatever reason, a request happens to fail (e.g. internet outage).

Currently this causes the app to crash. I created a fork and am trying to fix the issue.

First I have to fix all of these sections:

if (err || response.statusCode != 200) {
  console.log(body);
  this.emit("error", new Error("getMeasure error: " + response.statusCode));
  return this;
}

to check if response is in fact set, and an object containing a statusCode property. Otherwise a Cannot read property 'statusCode' of undefined type error is thrown.

Second I would like to remove the this.emit("error... statements and have a warning logged instead. (So that a single instance of a failed request does not crash the app.)

I am unsure what the correct way of doing so is. What is the intent of the original syntax? Why are the emitted errors thrown and show up in the console? Is there a way to emit, but still catch and handle the errors in my app?

I would appreciate your input!

Unhandled 'error'

Hi,

Is there a way to catch this error?

pi@rpi4:~/netatmo-test/node_modules/netatmo $ node test.js
events.js:160
      throw er; // Unhandled 'error' event
      ^

Error: Authenticate error: invalid_grant
    at netatmo.handleRequestError (/home/pi/netatmo-test/node_modules/netatmo/netatmo.js:46:15)
    at .<anonymous> (/home/pi/netatmo-test/node_modules/netatmo/netatmo.js:115:19)
    at Request.self.callback (/home/pi/netatmo-test/node_modules/request/request.js:186:22)
    at emitTwo (events.js:106:13)
    at Request.emit (events.js:191:7)
    at Request.<anonymous> (/home/pi/netatmo-test/node_modules/request/request.js:1081:10)
    at emitOne (events.js:96:13)
    at Request.emit (events.js:188:7)
    at IncomingMessage.<anonymous> (/home/pi/netatmo-test/node_modules/request/request.js:1001:12)
    at IncomingMessage.g (events.js:286:16)

test.js:

var netatmo = require('./netatmo');

var auth = {
  "client_id": "my_client_id",
  "client_secret": "my_client_secret",
  "username": "my_username",
  "password": "my_password",
};

try {
  var api = new netatmo(auth);
} catch(err) {
  console.log("api error " + err.message);
}

// EXAMPLE #1

// Get Stations Data
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/weatherstation/getstationsdata
try {
  api.getStationsData(function(err, devices) {
    console.log(devices);
  });
} catch(err) {
  console.log("getStationData error " + err.message);
}

Add "setpersonshome" API

Tech Docs: https://dev.netatmo.com/resources/technical/reference/security/setpersonshome

Add "setroomthermpoint" API

Tech doc: https://dev.netatmo.com/resources/technical/reference/energy/setroomthermpoint

Add "deletehomeschedule" API

Tech Docs: https://dev.netatmo.com/resources/technical/reference/energy/deletehomeschedule

Add "renamehomeschedule" API

Tech Docs: https://dev.netatmo.com/resources/technical/reference/energy/renamehomeschedule

Question: Options and callback parameters

Hello,

I've one question about a part of code in each api function:

if (options != null && callback == null) {
  callback = options;
  options = null;
}

What exactly does this?
When we use code from example:

// Get Thermostats Data
// See docs: https://dev.netatmo.com/dev/resources/technical/reference/thermostat/getthermostatsdata
var options = {
  device_id: '',
};

api.getThermostatsData(options);

This part of code erase "options", so options are not longer take into account. And this part of code create a 'bad' callback with the option parameter. This give this error because callback from return callback(err, devices); is not a function, it's option.

/home/user/Scripts/netatmo/node_modules/netatmo/netatmo.js:276
      return callback(err, devices);
             ^

TypeError: callback is not a function
    at netatmo.<anonymous> (/home/user/Scripts/netatmo/node_modules/netatmo/netatmo.js:276:14)
    at Request.self.callback (/home/user/Scripts/netatmo/node_modules/request/request.js:185:22)
    at Request.emit (node:events:390:28)
    at Request.<anonymous> (/home/user/Scripts/netatmo/node_modules/request/request.js:1154:10)
    at Request.emit (node:events:390:28)
    at IncomingMessage.<anonymous> (/home/user/Scripts/netatmo/node_modules/request/request.js:1076:12)
    at Object.onceWrapper (node:events:509:28)
    at IncomingMessage.emit (node:events:402:35)
    at endReadableNT (node:internal/streams/readable:1343:12)
    at processTicksAndRejections (node:internal/process/task_queues:83:21)

Thank you.

Webpack issue with 'fs' module

I'm very grateful for this module 👍

Just to help people out, if you use webpack and have this issue :

ERROR in ./~request/lib/bar.js
Module not found: Error: Cannot resolve module 'fs' in [..]

You need to add this to your webpack.config :

node: {
  fs: "empty"
}

Cf. josephsavona/valuable#9

👋 Looking for maintainers

Hi everyone! 👋

There's a lot of exciting, new things happening in my life (can't announce yet)! 🎉

I've had a blast working on this project since it's inception, but it's time to allow others to step in and take the lead.

I'll be around to help merge, give feedback, etc., however, I don't have the time to fully maintain the project.

I'm looking for new people to maintain the library and take over the project.

I'll provide guidance and onboard you (if you want).

What the project needs is someone with JS (maybe TS 👍 ) knowledge who also has access to one or more Netatmo devices. If that's you and you're interested, let me know.

In the meantime, be aware that I won't work on the open issues myself.

getHealthyHomeCoachData with empty options

getHealthyHomeCoachData has a different behavior if

1. options is null
2. options is {} (without device_id)

Replace request with axios

As great as request has been, it's pretty heavy. It has 22 dependencies.

Whereas axios has only 2.

Add "setpersonsaway" API

Tech Docs: https://dev.netatmo.com/resources/technical/reference/security/setpersonsaway

Error: Authentication error: No response

Starting last night at 03:00 I'm getting this error message:

"Error: Authentication error: No response"

Is anyone experiencing the same issue?

Add "createnewhomeschedule" API

Tech Docs: https://dev.netatmo.com/resources/technical/reference/energy/createnewhomeschedule

Include the setpoint_temp parameter in setThermpoint method

As mentioned in the documentation (https://dev.netatmo.com/dev/resources/technical/reference/thermostat/setthermpoint) setpoint_temp parameter let you select the desired temperature, in manual setpoint_mode.

It is not part of the current method:

  var form = {
    access_token: access_token,
    device_id: options.device_id,
    module_id: options.module_id,
    setpoint_mode: options.setpoint_mode,
};

Write tests

To bring this package up to standards, we need to have tests for each API call.

The API docs have definitions of what is required and optional and what is expected.

For example: https://dev.netatmo.com/apidocumentation/weather#getpublicdata

Name	Type	Required	Default	Description
lat_ne	number	Y		latitude of the north east corner of the requested area. -85 <= lat_ne <= 85 and lat_ne>lat_sw
lon_ne	number	Y		Longitude of the north east corner of the requested area. -180 <= lon_ne <= 180 and lon_ne>lon_sw
lat_sw	number	Y		latitude of the south west corner of the requested area. -85 <= lat_sw <= 85
lon_sw	number	Y		Longitude of the south west corner of the requested area. -180 <= lon_sw <= 180
required_data	string	N	''	To filter stations based on relevant measurements you want (e.g. rain will only return stations with rain gauges). You can find all measurements available on the Thermostat page.
filter	boolean	N	false	True to exclude station with abnormal temperature measures.

Client credentials grant type deprecated

" Authenticate error: unauthorized_client"
It looks like Netatmo has finaly disabled "Client credentials grant type" which was slated for October 2022. (https://dev.netatmo.com/apidocumentation/oauth)

One can generate an app with tokens on the netatmo dev site: https://dev.netatmo.com/apps/createanapp and I made a dirty fork to use this refresh token to request a new authorization_token:
https://github.com/arenddeboer/netatmo/blob/main/netatmo.js

I do wonder how long the refresh token generated on the netatmo dev site is valid, so this solution may not be workable if it expires.

Add "setroomthermmode" API

Tech Doc: https://dev.netatmo.com/resources/technical/reference/energy/setthermmode

Mobile app desync

I'm using your package through a node-red netamo package (fork of ssadams11).

As soon as the node calls the API, the mobile app loose the connection ("Your Netamo Relay is not connected anymore to our servers. Did you change the wifi password or unplugged the relay ?")^.

To "connect" it again, I have to set a new temperature thanks to the module itself (physically).

Add "homesdata" API

Tech docs: https://dev.netatmo.com/resources/technical/reference/energy/homesdata

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because we are using your CI build statuses to figure out when to notify you about breaking changes.

Since we did not receive a CI status on the greenkeeper/initial branch, we assume that you still need to configure it.

If you have already set up a CI for this repository, you might need to check your configuration. Make sure it will run on all new branches. If you don’t want it to run on every branch, you can whitelist branches starting with greenkeeper/.

We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

Add "addwebhook" API

Tech Docs: https://dev.netatmo.com/resources/technical/reference/security/addwebhook

An in-range update of request is breaking the build 🚨

Version 2.82.0 of request just got published.

Branch	Build failing 🚨
Dependency	request
Current Version	2.81.0
Type	dependency

This version is covered by your current version range and after updating it in your project the build failed.

request is a direct dependency of this project this is very likely breaking your project right now. If other packages depend on you it’s very likely also breaking them.
I recommend you give this issue a very high priority. I’m sure you can resolve this 💪

Status Details

• ✅ dependency-ci Dependencies checked Details
• ❌ continuous-integration/travis-ci/push The Travis CI build failed Details

---

Commits

The new version differs by 27 commits.

• 0ab5c36 2.82.0
• ffdf0d3 Updating deps.
• 4386836 Merge branch 'master' of github.com:request/request
• 1527407 Merge pull request #2703 from ryysud/add-nodejs-v8-to-travis
• 3afcbf8 Merge branch 'master' of github.com:request/request
• 479143d Update of hawk and qs to latest version (#2751)
• 169be11 Add Node.js v8 to Travis CI
• 643c43a Fixed some text in README.md (#2658)
• e8fca51 chore(package): update aws-sign2 to version 0.7.0 (#2635)
• e999203 Update README to simplify & update convenience methods (#2641)
• 6f286c8 lint fix, PR from pre-standard was merged with passing tests
• a765593 Add convenience method for HTTP OPTIONS (#2541)
• 52d6945 Add promise support section to README (#2605)
• b12a624 refactor(lint): replace eslint with standard (#2579)
• 29a0b17 Merge pull request #2598 from request/greenkeeper-codecov-2.0.2

There are 27 commits in total.

See the full diff

Not sure how things should work exactly?

There is a collection of frequently asked questions and of course you may always ask my humans.

---

Your Greenkeeper Bot 🌴

Add "partnerdevices" API

Tech Docs: https://dev.netatmo.com/resources/technical/reference/enterpriseapi/partnerdevices

Error: getMeasure error: Status code404

Trying to follow "Example #1", and api.getMeasure throws a 404 error.

Perhaps I don't know what to put for device_id, or module_id.

Switch to Getthermostatsdata, Gethomedata and Getstationsdata by November 30th.

I got this email today:

Friendly reminder: Getthermstate, Getuser and Devicelist will move from deprecated to shut down. On November 30th, we are proceeding to a structural change to make our APIs faster and more powerful. Unfortunately, old and deprecated API methods won’t be supported anymore. Make sure you amend your code and start using newer methods as soon as possible for a smooth transition:

• Replace Getthermstate with Getthermostatdata
• Replace Getuser with Getthermostatdata, Gethomedata or Getstationsdata
• Replace Devicelist with Getthermostatdata or Getstationsdata

So it looks like, there are some updates for the library required.

Missing credentials throws unhandled error event

I´m facing the following problem:

Passing empty credentials to object instantation causes an unhandled error event. If i pass valid information, the authenticated event will be successfully emitted and cought:

var api = new netatmo(auth);

 api.on("error", function(err) {

    console.log(err);
});

api.on("warning", function(warning) {

    console.log(warning);
});

api.on("authenticated", function() {

    console.log("authenticated");
});

Different type of error handling

Hello, this is more a questions or a suggestion than a bug but I'm interested why the error-handling - for example in getstationsdata - is how it is.

This is the current code which ends up inside the first if-statement if an error occurs without calling the callback which includes an never-filled err-parameter:

request({
    url: url,
    method: "GET",
    form: form,
  }, function (err, response, body) {
    if (err || response.statusCode != 200) {
      return this.handleRequestError(err, response, body, "getStationsDataError error");
    }

    body = JSON.parse(body);

    var devices = body.body.devices;

    this.emit('get-stationsdata', err, devices);

    if (callback) {
      return callback(err, devices);
    }

Wouldn't it make more sense if the callback would be called everytime if given, with or without an err-object. In this case implementations could rely on callbacks.
In my case I have a homebridge-plugin which polls the netatmo API regularly. Every now and then the Netatmo-API fails, I run into a soft-ban (too many calls) or get banned because I keep polling although the API return Error-500 because of some problems on the API server. I'm not a nodeJS-pro but I currently do not see a way how to handle the errors and still continue the normal logic.

So in my case something like this would be way more useful. What do you think?

}, function (err, response, body) {
    if (err || response.statusCode != 200) {
      this.handleRequestError(err, response, body, "getStationsDataError error");
      body = '{"body":{"devices":[]}}';
      err = (err)?err:true;
    }

Update to last Thermostat API

Since March 5th, 2018, Thermostat API has evolved and now supports Valves.
With this update Setthermpoint is deprecated -> a new function Setroomthermpoint appears.

Is it possible to include this new function?

Regards

Add "switchhomeschedule" API

Tech docs: https://dev.netatmo.com/resources/technical/reference/energy/switchhomeschedule

Write more tests

Add "homestatus" API

Tech docs: https://dev.netatmo.com/resources/technical/reference/energy/homestatus

Add "dropwebhook" API

Tech Docs: https://dev.netatmo.com/resources/technical/reference/security/dropwebhook