Skip to content

Commit 44f88be

Browse files
fh1chfh1ch
committed
feat: add JSDoc inline documentation and gh-page publishing
1 parent e58b591 commit 44f88be

6 files changed

Lines changed: 156 additions & 85 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
node_modules/
22
npm-debug.log
33
reports/
4+
docs/

‎.jscsrc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
"maximumLineLength": 320,
44
"requireSemicolons": true,
55
"requireCamelCaseOrUpperCaseIdentifiers": false,
6-
"requireCurlyBraces": false
6+
"requireCurlyBraces": false,
7+
"jsDoc": false
78
}

‎.travis.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,14 @@ script:
1313
- "npm run test"
1414
- "cat ./reports/coverage/lcov.info | ./node_modules/.bin/coveralls"
1515
- "npm run integration"
16+
- "npm run docs"
17+
18+
deploy:
19+
provider: pages
20+
local_dir: ./docs
21+
skip_cleanup: true
22+
github_token: $GITHUB_API_KEY
23+
on:
24+
branch: master
1625

1726
sudo: false

‎README.md‎

Lines changed: 49 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ interact with building automation devices defined by ASHRAE.
99
[![](https://codeclimate.com/github/fh1ch/node-bacstack/badges/gpa.svg)](https://codeclimate.com/github/fh1ch/node-bacstack)
1010
[![](https://david-dm.org/fh1ch/node-bacstack/status.svg)](https://david-dm.org/fh1ch/node-bacstack)
1111

12-
> **Note:** This is an early prototype and shall not be considerate as stable.
12+
> **Note:** This is an early prototype and shall not be considered as stable.
1313
> Use it with caution and at your own risk!
1414
1515
## Usage
@@ -20,115 +20,82 @@ Add Node BACstack to your project by using:
2020
$ npm install --save bacstack
2121
```
2222

23-
#### Client
23+
The API documentation is available under **[fh1ch.github.io/node-bacstack](https://fh1ch.github.io/node-bacstack)**.
2424

25-
To be able to communicate to BACNET devices, you have to initialize a new
26-
bacstack instance. Hereby, following options are avilable:
27-
28-
- `option` *[object]* - The options object used for parameterising the bacstack.
29-
- `port` *[number]* - BACNET communication port for listening and sending. Default is `47808`. *Optional*.
30-
- `interface` *[string]* - Specific BACNET communication interface if different from primary one. *Optional*.
31-
- `broadcastAddress` *[string]* - The address used for broadcast messages. Default is `255.255.255.255`. *Optional*.
32-
- `adpuTimeout` *[number]* - The timeout in milliseconds until a transaction should be interpreted as error. Default is `3000`. *Optional*.
25+
### Example
3326

3427
``` js
3528
var bacnet = require('bacstack');
36-
var client = bacnet({
37-
port: 47809, // Use BAC1 as communication port
38-
interface: '192.168.251.10', // Listen on a specific interface
39-
broadcastAddress: '192.168.251.255', // Use the subnet broadcast address
40-
adpuTimeout: 6000 // Wait twice as long for response
41-
});
42-
```
43-
44-
#### Who Is
45-
46-
The `whoIs` command discovers all BACNET devices in the network.
4729

48-
- `lowLimit` *[number]* - Minimal device instance number to search for. *Optional*.
49-
- `highLimit` *[number]* - Maximal device instance number to search for. *Optional*.
50-
- `address` *[string]* - Unicast address if command should device directly. *Optional*.
51-
52-
``` js
53-
var bacnet = require('bacstack');
54-
var client = bacnet();
30+
// Initialize BACStack
31+
var client = bacnet({adpuTimeout: 6000});
5532

33+
// Discover Devices
5634
client.on('iAm', function(address, deviceId, maxAdpu, segmentation, vendorId) {
5735
console.log('address: ', address, ' - deviceId: ', deviceId, ' - maxAdpu: ', maxAdpu, ' - segmentation: ', segmentation, ' - vendorId: ', vendorId);
5836
});
59-
6037
client.whoIs();
61-
```
6238

63-
#### Read Property
64-
65-
The `readProperty` command reads a single property of an object from a device.
66-
67-
- `address` *[string]* - IP address of the target device.
68-
- `objectType` *[number]* - The BACNET object type to read.
69-
- `objectInstance` *[number]* - The BACNET object instance to read.
70-
- `propertyId` *[number]* - The BACNET property id in the specified object to read.
71-
- `arrayIndex` *[number]* - The array index of the property to be read.
72-
- `next` *[function]* - The callback containing an error, in case of a failure and value object in case of success.
73-
74-
``` js
75-
var bacnet = require('bacstack');
76-
var client = bacnet();
77-
78-
client.readProperty('192.168.1.43', 8, 44301, 28, null, function(err, value) {
39+
// Read Device Object
40+
var requestArray = [
41+
{objectIdentifier: {type: 8, instance: 4194303}, propertyReferences: [{propertyIdentifier: 8}]}
42+
];
43+
client.readPropertyMultiple('192.168.1.43', requestArray, function(err, value) {
7944
console.log('value: ', value);
8045
});
8146
```
8247

83-
#### Write Property
48+
## Contributing
8449

85-
The `writeProperty` command writes a single property of an object to a device.
50+
Implementing and maintaining a protocol stack is a lot of work, therefore any
51+
help is appreciated, from creating issues, to contributing documentation, fixing
52+
issues and adding new features.
8653

87-
- `address` *[string]* - IP address of the target device.
88-
- `objectType` *[number]* - The BACNET object type to write.
89-
- `objectInstance` *[number]* - IP address of the target device.
90-
- `propertyId` *[number]* - The BACNET property id in the specified object to write.
91-
- `priority` *[number]* - The priority to be used for writing to the property.
92-
- `valueList` *[array]* - A list of values to be written to the speicifed property. The `Tag` value has to be a `BacnetApplicationTags` declaration as specified in `lib/bacnet-enum.js`.
93-
- `next` *[function]* - The callback containing an error, in case of a failure and value object in case of success.
54+
Please follow the best-practice contribution guidelines as mentioned below when
55+
submitting any changes.
9456

95-
propertyId, ,
57+
### Code Style
9658

97-
``` js
98-
var bacnet = require('bacstack');
99-
var client = bacnet();
59+
This module uses the [Google JavaScript Code-Style](https://google.github.io/styleguide/javascriptguide.xml)
60+
and enforces it using [JSCS](http://jscs.info/) as additional linter beneath
61+
[JSHint](http://jshint.com/). You can test if your changes comply with the code
62+
style by executing:
10063

101-
client.writeProperty('192.168.1.43', 8, 44301, 28, 12, [{Tag: 4, Value: 100}], function(err, value) {
102-
console.log('value: ', value);
103-
});
64+
``` sh
65+
$ npm run lint
10466
```
10567

106-
#### Read Property Multiple
68+
### Testing and Coverage
10769

108-
The `readPropertyMultiple` command reads multiple properties in multiple objects
109-
from a device.
70+
Testing is done using [Mocha](https://mochajs.org/) and is separated into two
71+
sets, `unit` and `integration`. While unit tries to test on function level,
72+
including synthetic decoding and encoding, the integration tests are using real
73+
recorded data and are only mocking the transport layer.
11074

111-
- `address` *[string]* - IP address of the target device.
112-
- `propertyIdAndArrayIndex` *[array]* - List of object and property specifications to be read.
113-
- `objectIdentifier` *[object]* - Specifies which object to read.
114-
- `type` *[number]* - The BACNET object type to read.
115-
- `instance` *[number]* - The BACNET object instance to read.
116-
- `propertyReferences` *[array]* - List of properties to be read.
117-
- `propertyIdentifier` *[number]* - The BACNET property id in the specified object to read. Also supports `8` for *all* properties.
118-
- `next` *[function]* - The callback containing an error, in case of a failure and value object in case of success.
75+
For both sets, the test-coverage is calculated using [Istanbul](https://istanbul.js.org/).
76+
Running the tests and calculating the coverage can be done locally by executing:
11977

120-
``` js
121-
var bacnet = require('bacstack');
122-
var client = bacnet();
78+
``` sh
79+
$ npm run test
80+
$ npm run integration
81+
```
12382

124-
var requestArray = [
125-
{objectIdentifier: {type: 8, instance: 4194303}, propertyReferences: [{propertyIdentifier: 8}]}
126-
];
127-
client.readPropertyMultiple('192.168.1.43', requestArray, function(err, value) {
128-
console.log('value: ', value);
129-
});
83+
It is expected that new features or fixes do not negatively impact the test
84+
results or the coverage.
85+
86+
### Documentation
87+
88+
The API documentation is generated using [JSDoc](http://usejsdoc.org/) and
89+
relies on in-line JSDoc3 syntax. The documentation can also be built locally by
90+
executing:
91+
92+
``` sh
93+
$ npm run docs
13094
```
13195

96+
It is expected that new features or changes are reflected in the documentation
97+
as well.
98+
13299
## License
133100

134101
[The MIT License](http://opensource.org/licenses/MIT)

‎index.js‎

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,24 @@ var events = require('events');
55
var baClient = require('./lib/bacnet-client');
66
var baEnum = require('./lib/bacnet-enum');
77

8+
/**
9+
* To be able to communicate to BACNET devices, you have to initialize a new bacstack instance.
10+
* @class bacstack
11+
* @param {object=} settings - The options object used for parameterising the bacstack.
12+
* @param {number=} [settings.port=47808] - BACNET communication port for listening and sending.
13+
* @param {string=} settings.interface - Specific BACNET communication interface if different from primary one.
14+
* @param {string=} [settings.broadcastAddress=255.255.255.255] - The address used for broadcast messages.
15+
* @param {number=} [settings.adpuTimeout=3000] - The timeout in milliseconds until a transaction should be interpreted as error.
16+
* @example
17+
* var bacnet = require('bacstack');
18+
*
19+
* var client = bacnet({
20+
* port: 47809, // Use BAC1 as communication port
21+
* interface: '192.168.251.10', // Listen on a specific interface
22+
* broadcastAddress: '192.168.251.255', // Use the subnet broadcast address
23+
* adpuTimeout: 6000 // Wait twice as long for response
24+
* });
25+
*/
826
module.exports = function(settings) {
927
var self = new events.EventEmitter();
1028

@@ -22,21 +40,93 @@ module.exports = function(settings) {
2240
// Public enums
2341
self.enum = baEnum;
2442

25-
// Public functions
43+
/**
44+
* The whoIs command discovers all BACNET devices in a network.
45+
* @function bacstack.whoIs
46+
* @param {number=} lowLimit - Minimal device instance number to search for.
47+
* @param {number=} highLimit - Maximal device instance number to search for.
48+
* @param {string=} address - Unicast address if command should device directly.
49+
* @fires bacstack.iAm
50+
* @example
51+
* client.whoIs();
52+
*/
2653
self.whoIs = function(lowLimit, highLimit, address) {
2754
client.whoIs(lowLimit, highLimit, address, function(address, deviceId, maxAdpu, segmentation, vendorId) {
55+
56+
/**
57+
* @event bacstack.iAm
58+
* @param {string} address - The IP address of the detected device.
59+
* @param {number} deviceId - The BACNET device-id of the detected device.
60+
* @param {number} maxAdpu - The max ADPU size the detected device is supporting.
61+
* @param {number} segmentation - The type of segmentation the detected device is supporting.
62+
* @param {number} vendorId - The BACNET vendor-id of the detected device.
63+
* @example
64+
* client.on('iAm', function(address, deviceId, maxAdpu, segmentation, vendorId) {
65+
* console.log('address: ', address, ' - deviceId: ', deviceId, ' - maxAdpu: ', maxAdpu, ' - segmentation: ', segmentation, ' - vendorId: ', vendorId);
66+
* });
67+
*/
2868
self.emit('iAm', address, deviceId, maxAdpu, segmentation, vendorId);
2969
});
3070
};
3171

72+
/**
73+
* The readProperty command reads a single property of an object from a device.
74+
* @function bacstack.readProperty
75+
* @param {string} address - IP address of the target device.
76+
* @param {number} objectType - The BACNET object type to read.
77+
* @param {number} objectInstance - The BACNET object instance to read.
78+
* @param {number} propertyId - The BACNET property id in the specified object to read.
79+
* @param {number=} arrayIndex - The array index of the property to be read.
80+
* @param {function} next - The callback containing an error, in case of a failure and value object in case of success.
81+
* @example
82+
* client.readProperty('192.168.1.43', 8, 44301, 28, null, function(err, value) {
83+
* console.log('value: ', value);
84+
* });
85+
*/
3286
self.readProperty = function(address, objectType, objectInstance, propertyId, arrayIndex, next) {
3387
client.readProperty(address, objectType, objectInstance, propertyId, arrayIndex, next);
3488
};
3589

90+
/**
91+
* The writeProperty command writes a single property of an object to a device.
92+
* @function bacstack.writeProperty
93+
* @param {string} address - IP address of the target device.
94+
* @param {number} objectType - The BACNET object type to write.
95+
* @param {number} objectInstance - The BACNET object instance to write.
96+
* @param {number} propertyId - The BACNET property id in the specified object to write.
97+
* @param {number} priority - The priority to be used for writing to the property.
98+
* @param {object[]} valueList - A list of values to be written to the speicifed property.
99+
* @param {number} valueList.Tag - The data-type of the value to be written. Has to be a BacnetApplicationTags declaration as specified in lib/bacnet-enum.js.
100+
* @param {number} valueList.Value - The actual value to be written.
101+
* @param {function} next - The callback containing an error, in case of a failure and value object in case of success.
102+
* @example
103+
* client.writeProperty('192.168.1.43', 8, 44301, 28, 12, [{Tag: 4, Value: 100}], function(err, value) {
104+
* console.log('value: ', value);
105+
* });
106+
*/
36107
self.writeProperty = function(address, objectType, objectInstance, propertyId, priority, valueList, next) {
37108
client.writeProperty(address, objectType, objectInstance, propertyId, priority, valueList, next);
38109
};
39110

111+
/**
112+
* The readPropertyMultiple command reads multiple properties in multiple objects from a device.
113+
* @function bacstack.readPropertyMultiple
114+
* @param {string} address - IP address of the target device.
115+
* @param {object[]} propertyIdAndArrayIndex - List of object and property specifications to be read.
116+
* @param {object} propertyIdAndArrayIndex.objectIdentifier - Specifies which object to read.
117+
* @param {number} propertyIdAndArrayIndex.objectIdentifier.type - The BACNET object type to read.
118+
* @param {number} propertyIdAndArrayIndex.objectIdentifier.instance - The BACNET object instance to read.
119+
* @param {object[]} propertyIdAndArrayIndex.propertyReferences - List of properties to be read.
120+
* @param {number} propertyIdAndArrayIndex.propertyReferences.propertyIdentifier - The BACNET property id in the specified object to read. Also supports 8 for all properties.
121+
* @param {function} next - The callback containing an error, in case of a failure and value object in case of success.
122+
* @example
123+
* var requestArray = [
124+
* {objectIdentifier: {type: 8, instance: 4194303}, propertyReferences: [{propertyIdentifier: 8}]}
125+
* ];
126+
* client.readPropertyMultiple('192.168.1.43', requestArray, function(err, value) {
127+
* console.log('value: ', value);
128+
* });
129+
*/
40130
self.readPropertyMultiple = function(address, propertyIdAndArrayIndex, next) {
41131
client.readPropertyMultiple(address, propertyIdAndArrayIndex, next);
42132
};

‎package.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@
66
"scripts": {
77
"lint": "jshint lib/ index.js && jscs lib/ index.js",
88
"test": "istanbul cover --dir reports/coverage node_modules/mocha/bin/_mocha -- test/unit/*.spec.js",
9-
"integration": "istanbul cover --dir reports/coverage node_modules/mocha/bin/_mocha -- test/integration/*.spec.js"
9+
"integration": "istanbul cover --dir reports/coverage node_modules/mocha/bin/_mocha -- test/integration/*.spec.js",
10+
"docs": "jsdoc -d ./docs -t node_modules/docdash ./lib ./index.js ./README.md"
1011
},
1112
"repository": {
1213
"type": "git",
@@ -35,8 +36,10 @@
3536
},
3637
"devDependencies": {
3738
"chai": "^3.5.0",
39+
"docdash": "^0.4.0",
3840
"istanbul": "^0.4.5",
3941
"jscs": "^3.0.7",
42+
"jsdoc": "^3.4.3",
4043
"jshint": "^2.9.4",
4144
"mocha": "^3.2.0"
4245
}

0 commit comments

Comments
 (0)