<commit_before>#DeviceHive JavaScript framework

[DeviceHive]: http://devicehive.com "DeviceHive framework"
[DataArt]: http://dataart.com "DataArt"

[DeviceHive] turns any connected device into the part of Internet of Things.
It provides the communication layer, control software and multi-platform
libraries to bootstrap development of smart energy, home automation, remote
sensing, telemetry, remote control and monitoring software and much more.

Connect embedded Linux using Python or C++ libraries and JSON protocol or
connect AVR, Microchip devices using lightweight C libraries and BINARY protocol.
Develop client applications using HTML5/JavaScript, iOS and Android libraries.
For solutions involving gateways, there is also gateway middleware that allows
to interface with devices connected to it. Leave communications to [DeviceHive]
and focus on actual product and innovation.

JavaScript framework is a wrapper around [DeviceHive RESTful protocol](http://www.devicehive.com/restful) that includes a set of methods to access corresponding [DeviceHive] resources.

#Components

##Client

This library could be a very good choice to quickly prototype an HTML client for your custom device. It could also be used in complex applications to enable interaction with the [DeviceHive] server from the client-side components.

The library supports the following actions:

* Authenticate with login and password or with an access key.
* Get information about [DeviceHive] networks, devices and device classes
* Get current state of equipment that devices have onboard
* Get real-time notifications from devices about various events
* Send a command to a particular device

##Device

The library supports the following actions:

* Authenticate with a device key or with an access key.
* Register and update a device in the [DeviceHive] network
* Get information about the current device
* Get and update real-time commands from clients
* Send a notification to the cloud

#Compatibility

**Client** and **Device** libraries could be used in the following environments:

* Chrome
* Safari
* Firefox
* IE 10, 11

`Node.js` support will be added in future, but still you can leverage [DeviceHive] on `node` by workarounding transport related specifics. 
For example you can install a library which implements XMLHttpRequest and use only `longpolling` channel.

#Installation:

##Browser

Install package with bower:

```sh
$ bower install devicehive
```

or download package files from [`build\browser`](build/browser) folder. 

After that you should add references to your HTML file.

You can also use `JQuery` wrappers to utilize `Deferred`s instead of node-style callbacks.

#Usage

Create new instance of the `DHClient` or `DHDevice`

```js
// Create DHClient instance specifying login and password as an auth parameters
var dhClient = new DHClient("http://xxxxx.pg.devicehive.com/api", "login", "password");

// Create DHClient instance specifying access key as an auth parameter
var dhClient = new DHClient("http://xxxxx.pg.devicehive.com/api", "AccessKeyExampleAccessKeyExampleAccessKeyEx=");

// Create DHDevice instance specifying device id and device key as an auth parameters
var dhDevice = new DHDevice("http://xxxxx.pg.devicehive.com/api", "someDeviceId_123-456", "someCustomDeviceKey");

// Create DHDevice instance specifying device id and access key as an auth parameters
var dhDevice = new DHDevice("http://xxxxx.pg.devicehive.com/api", "someDeviceId_123-456", "AccessKeyExampleAccessKeyExampleAccessKeyEx=");
```

or if you want to use `Deferred`s use builders from `JQuery` object

```js
var dhClient = $.dhClient("http://xxxx.pg.devicehive.com/api", "login", "password");
```

After creating a new instance you will be able to get relevant information from the [DeviceHive] cloud

```js
// Use DHClient library to get information about devices registered in the cloud
dhClient.getDevices(function(err, devices){
    if(!err)
        doWork(devices);
});
```

also you can register devices and update data in the cloud

```js
// Use DHDevice library to register your device in the cloud.
// It will be registered with an id specified during DHDevice instance creation 
dhDevice.registerDevice({
    name: "<NAME>",
    // device key which can be used for device authentication.
    key: "some device key",
    // object with a description of the device class or existing device class id
    deviceClass: {
        name: 'My Device Class',
        version: '0.0.1',
        equipment: [
            { name: 'Example sensor', type: 'sensor', code: '1234' }
        ]
    }
}, function(err, res) {
    console.log(err ? 'failed' : 'success');
});
```

You can check [Core Implementation](src/core/devicehive.js), [DHClient Implementation](src/client/client.js) and [DHDevice Implementation](src/device/device.js) or read [DeviceHive RESTful protocol] reference to get more information about the supported methods.

##Channels

The framework also implements a facility to continuously receive device notifications, send notification, receive client commands and send client commands.
These features utilizes WebSocket or HTTP long-polling mechanisms supported by [DeviceHive]. In order to provide that functionality, the library uses a concept of channels to transmit messages between the server and client. 
Clients and devices should simply open a channel, subscribe to messages and then handle them in the corresponding callback methods.

To open the channel

```js
dhClient.openChannel(callbackFunction, channelName)
```

Channel names are `websocket` and `longpolling`. If `channelName` is not passed then the first compatible channel will be opened.

You can also subscribe for a channel state changed event:<commit_msg>Fixed RESTful protocol links in the doc<commit_after>#DeviceHive JavaScript framework

[DeviceHive]: http://devicehive.com "DeviceHive framework"
[DataArt]: http://dataart.com "DataArt"
[DeviceHive RESTful protocol]: http://www.devicehive.com/restful "DeviceHive RESTful protocol"

[DeviceHive] turns any connected device into the part of Internet of Things.
It provides the communication layer, control software and multi-platform
libraries to bootstrap development of smart energy, home automation, remote
sensing, telemetry, remote control and monitoring software and much more.

Connect embedded Linux using Python or C++ libraries and JSON protocol or
connect AVR, Microchip devices using lightweight C libraries and BINARY protocol.
Develop client applications using HTML5/JavaScript, iOS and Android libraries.
For solutions involving gateways, there is also gateway middleware that allows
to interface with devices connected to it. Leave communications to [DeviceHive]
and focus on actual product and innovation.

JavaScript framework is a wrapper around [DeviceHive RESTful protocol] that includes a set of methods to access corresponding [DeviceHive] resources.

#Components

##Client

This library could be a very good choice to quickly prototype an HTML client for your custom device. It could also be used in complex applications to enable interaction with the [DeviceHive] server from the client-side components.

The library supports the following actions:

* Authenticate with login and password or with an access key.
* Get information about [DeviceHive] networks, devices and device classes
* Get current state of equipment that devices have onboard
* Get real-time notifications from devices about various events
* Send a command to a particular device

##Device

The library supports the following actions:

* Authenticate with a device key or with an access key.
* Register and update a device in the [DeviceHive] network
* Get information about the current device
* Get and update real-time commands from clients
* Send a notification to the cloud

#Compatibility

**Client** and **Device** libraries could be used in the following environments:

* Chrome
* Safari
* Firefox
* IE 10, 11

`Node.js` support will be added in future, but still you can leverage [DeviceHive] on `node` by workarounding transport related specifics. 
For example you can install a library which implements XMLHttpRequest and use only `longpolling` channel.

#Installation:

##Browser

Install package with bower:

```sh
$ bower install devicehive
```

or download package files from [`build\browser`](build/browser) folder. 

After that you should add references to your HTML file.

You can also use `JQuery` wrappers to utilize `Deferred`s instead of node-style callbacks.

#Usage

Create new instance of the `DHClient` or `DHDevice`

```js
// Create DHClient instance specifying login and password as an auth parameters
var dhClient = new DHClient("http://xxxxx.pg.devicehive.com/api", "login", "password");

// Create DHClient instance specifying access key as an auth parameter
var dhClient = new DHClient("http://xxxxx.pg.devicehive.com/api", "AccessKeyExampleAccessKeyExampleAccessKeyEx=");

// Create DHDevice instance specifying device id and device key as an auth parameters
var dhDevice = new DHDevice("http://xxxxx.pg.devicehive.com/api", "someDeviceId_123-456", "someCustomDeviceKey");

// Create DHDevice instance specifying device id and access key as an auth parameters
var dhDevice = new DHDevice("http://xxxxx.pg.devicehive.com/api", "someDeviceId_123-456", "AccessKeyExampleAccessKeyExampleAccessKeyEx=");
```

or if you want to use `Deferred`s use builders from `JQuery` object

```js
var dhClient = $.dhClient("http://xxxx.pg.devicehive.com/api", "login", "password");
```

After creating a new instance you will be able to get relevant information from the [DeviceHive] cloud

```js
// Use DHClient library to get information about devices registered in the cloud
dhClient.getDevices(function(err, devices){
    if(!err)
        doWork(devices);
});
```

also you can register devices and update data in the cloud

```js
// Use DHDevice library to register your device in the cloud.
// It will be registered with an id specified during DHDevice instance creation 
dhDevice.registerDevice({
    name: "My Device",
    // device key which can be used for device authentication.
    key: "some device key",
    // object with a description of the device class or existing device class id
    deviceClass: {
        name: 'My Device Class',
        version: '0.0.1',
        equipment: [
            { name: 'Example sensor', type: 'sensor', code: '1234' }
        ]
    }
}, function(err, res) {
    console.log(err ? 'failed' : 'success');
});
```

You can check [Core Implementation](src/core/devicehive.js), [DHClient Implementation](src/client/client.js) and [DHDevice Implementation](src/device/device.js) or read [DeviceHive RESTful protocol] reference to get more information about supported methods.

##Channels

The framework also implements a facility to continuously receive device notifications, send notification, receive client commands and send client commands.
These features utilizes WebSocket or HTTP long-polling mechanisms supported by [DeviceHive]. In order to provide that functionality, the library uses a concept of channels to transmit messages between the server and client. 
Clients and devices should simply open a channel, subscribe to messages and then handle them in the corresponding callback methods.

To open the channel

```js
dhClient.openChannel(callbackFunction, channelName)
```

Channel names are `websocket` and `longpolling`. If `channelName` is not passed then the first compatible channel will be opened.

You can also subscribe for a channel state changed event:
{'fraction_non_alphanumeric': 0.07428867940845801, 'fraction_numerical': 0.0041511718412176775, 'mean_word_length': 4.776223776223776, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3413710', 'n_tokens_mistral': 3019, 'n_tokens_neox': 2895, 'n_words': 1424}