Update docs

Daxbot · Oct 3, 2021 · 6178ec7 · 6178ec7
1 parent 338032a
commit 6178ec7
Show file tree

Hide file tree

Showing 40 changed files with 4,185 additions and 1,120 deletions.
diff --git a/.jsdoc.json b/.jsdoc.json
@@ -28,7 +28,8 @@
     },
     "templates": {
         "default": {
-            "useLongnameInNav": true
+            "useLongnameInNav": true,
+            "includeDate": false
         }
     }
 }
diff --git a/README.md b/README.md
@@ -5,6 +5,9 @@ CANopen see http://www.can-cia.org/
 
 This library allows the manipulation of CANopen devices as defined in CiA 301.
 
+## Documentation
+Pre-built documentation is available here: https://daxbot.github.io/node-canopen/
+
 ## Protocols
 ### Emergency - EMCY
 The CANopen emergency protocol is used to indicate internal errors with a

diff --git a/docs/DataObject.html b/docs/DataObject.html
diff --git a/docs/Device.html b/docs/Device.html
diff --git a/docs/Eds.html b/docs/Eds.html
diff --git a/docs/EdsError.html b/docs/EdsError.html
diff --git a/docs/Emcy.html b/docs/Emcy.html
diff --git a/docs/EmcyMessage.html b/docs/EmcyMessage.html
diff --git a/docs/Lss.html b/docs/Lss.html
diff --git a/docs/LssError.html b/docs/LssError.html
diff --git a/docs/Nmt.html b/docs/Nmt.html
diff --git a/docs/Pdo.html b/docs/Pdo.html
diff --git a/docs/SdoClient.html b/docs/SdoClient.html
diff --git a/docs/SdoError.html b/docs/SdoError.html
diff --git a/docs/SdoServer.html b/docs/SdoServer.html
diff --git a/docs/Sync.html b/docs/Sync.html
diff --git a/docs/Time.html b/docs/Time.html
diff --git a/docs/device.js.html b/docs/device.js.html
diff --git a/docs/eds.js.html b/docs/eds.js.html
diff --git a/docs/global.html b/docs/global.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/protocol_emcy.js.html b/docs/protocol_emcy.js.html
diff --git a/docs/protocol_lss.js.html b/docs/protocol_lss.js.html
diff --git a/docs/protocol_nmt.js.html b/docs/protocol_nmt.js.html
diff --git a/docs/protocol_pdo.js.html b/docs/protocol_pdo.js.html
diff --git a/docs/protocol_sdo.js.html b/docs/protocol_sdo.js.html
diff --git a/docs/protocol_sync.js.html b/docs/protocol_sync.js.html
diff --git a/docs/protocol_time.js.html b/docs/protocol_time.js.html
diff --git a/examples/eds_creation.js b/examples/eds_creation.js
@@ -10,19 +10,19 @@
 const { Eds, ObjectType, AccessType, DataType } = require('../index');
 const os = require("os");
 
-/** Step 1: Instantiate a new EDS object. */
+// Step 1: Instantiate a new EDS object.
 const eds = new Eds();
 
-/** Step 2: Edit file info. */
+// Step 2: Edit file info.
 eds.fileName = 'example.eds';
 eds.fileVersion = '1'
 eds.fileRevision = '1'
-eds.EDSVersion = '4.0'
+eds.edsVersion = '4.0'
 eds.description = 'An example EDS file';
 eds.creationDate = new Date();
 eds.createdBy = os.userInfo().username;
 
-/** Step 3: Add entries. */
+// Step 3: Add entries.
 eds.addEntry(0x1016, {
     parameterName:  'Consumer heartbeat time',
     objectType:     ObjectType.ARRAY,
@@ -53,5 +53,5 @@ eds.addEntry(0x2000, {
     defaultValue:   '00000000000000000000',
 });
 
-/** Step 4: Write to disk */
-eds.save('example.eds');
+// Step 4: Write to disk.
+eds.save();
diff --git a/examples/nmt_heartbeat.js b/examples/nmt_heartbeat.js
@@ -23,12 +23,13 @@ channel.addListener('onMessage', (message) => device.receive(message));
 device.setTransmitFunction((message) => channel.send(message));
 
 device.init();
-device.nmt.start();
 channel.start();
 
-// Step 5: Stop the node using NMT commands.
+device.nmt.start();
+
 setTimeout(() => {
-    device.nmt.stopNode(device.id);
+    // Step 5: Stop the node using NMT broadcast.
+    device.nmt.stopNode(0);
     setTimeout(() => {
         device.nmt.stop();
         channel.stop();

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "canopen",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "CANopen implementation for Javascript",
   "main": "index.js",
   "scripts": {

diff --git a/source/device.js b/source/device.js
@@ -12,7 +12,7 @@ const { Pdo } = require('./protocol/pdo');
 const { SdoClient, SdoServer } = require('./protocol/sdo');
 const { Sync } = require('./protocol/sync');
 const { Time } = require('./protocol/time');
-const { Eds, DataObject } = require('./eds');
+const { Eds, EdsError, DataObject } = require('./eds');
 
 /**
  * A CANopen device.
@@ -33,6 +33,17 @@ const { Eds, DataObject } = require('./eds');
  * @fires 'sync' on consuming a synchronization object.
  * @fires 'time' on consuming a time stamp object.
  * @fires 'pdo' on updating a mapped pdo object.
+ * @example
+ * const can = require('socketcan');
+ *
+ * const channel = can.createRawChannel('can0');
+ * const device = new Device({ id: 0xa });
+ *
+ * channel.addListener('onMessage', (message) => device.receive(message));
+ * device.setTransmitFunction((message) => channel.send(message));
+ *
+ * device.init();
+ * channel.start();
  */
 class Device extends EventEmitter {
     constructor({ id, eds, loopback=false }) {
@@ -95,12 +106,14 @@ class Device extends EventEmitter {
     }
 
     /**
-     * Called with each outgoing CAN message.
+     * Called with each outgoing CAN message. This method should not be called
+     * directly - use the protocol objects instead.
      *
      * @param {object} message - CAN frame.
      * @param {number} message.id - CAN message identifier.
      * @param {Buffer} message.data - CAN message data;
      * @param {number} message.len - CAN message length in bytes.
+     * @protected
      */
     send(message) {
         if(this._send === undefined)
@@ -131,7 +144,7 @@ class Device extends EventEmitter {
     getValue(index) {
         const entry = this.eds.getEntry(index);
         if(!entry)
-            throw ReferenceError("Entry does not exist");
+            throw new EdsError("Entry does not exist");
 
         return entry.value;
     }
@@ -146,7 +159,7 @@ class Device extends EventEmitter {
     getValueArray(index, subIndex) {
         const entry = this.eds.getSubEntry(index, subIndex);
         if(!entry)
-            throw ReferenceError("Entry does not exist");
+            throw new EdsError("Entry does not exist");
 
         return entry.value;
     }
@@ -160,7 +173,7 @@ class Device extends EventEmitter {
     getRaw(index) {
         const entry = this.eds.getEntry(index);
         if(!entry)
-            throw ReferenceError("Entry does not exist");
+            throw new EdsError("Entry does not exist");
 
         return entry.raw;
     }
@@ -175,7 +188,7 @@ class Device extends EventEmitter {
     getRawArray(index, subIndex) {
         const entry = this.eds.getSubEntry(index, subIndex);
         if(!entry)
-            throw ReferenceError("Entry does not exist");
+            throw new EdsError("Entry does not exist");
 
         return entry.raw;
     }
@@ -189,7 +202,7 @@ class Device extends EventEmitter {
     setValue(index, value) {
         const entry = this.eds.getEntry(index);
         if(!entry)
-            throw ReferenceError("Entry does not exist");
+            throw new EdsError("Entry does not exist");
 
         entry.value = value;
     }
@@ -204,7 +217,7 @@ class Device extends EventEmitter {
     setValueArray(index, subIndex, value) {
         const entry = this.eds.getSubEntry(index, subIndex);
         if(!entry)
-            throw ReferenceError("Entry does not exist");
+            throw new EdsError("Entry does not exist");
 
         entry.value = value;
     }
@@ -218,7 +231,7 @@ class Device extends EventEmitter {
     setRaw(index, raw) {
         const entry = this.eds.getEntry(index);
         if(!entry)
-            throw ReferenceError("Entry does not exist");
+            throw new EdsError("Entry does not exist");
 
         entry.raw = raw;
     }
@@ -233,7 +246,7 @@ class Device extends EventEmitter {
     setRawArray(index, subIndex, raw) {
         const entry = this.eds.getSubEntry(index, subIndex);
         if(!entry)
-            throw ReferenceError("Entry does not exist");
+            throw new EdsError("Entry does not exist");
 
         entry.raw = raw;
     }

diff --git a/source/eds.js b/source/eds.js
@@ -688,7 +688,7 @@ class DataObject extends EventEmitter {
     }
 
     /**
-     * Size of the raw data including sub-entries.
+     * Size of the raw data in bytes including sub-entries.
      *
      * @type {number}
      */
@@ -810,6 +810,26 @@ class DataObject extends EventEmitter {
  * This class provides methods for loading and saving CANopen EDS v4.0 files.
  *
  * @see CiA306 "Electronic data sheet specification for CANopen"
+ * @example
+ * const eds = new Eds();
+ *
+ * eds.fileName = 'example.eds';
+ * eds.fileVersion = '1'
+ * eds.fileRevision = '1'
+ * eds.edsVersion = '4.0'
+ * eds.description = 'An example EDS file';
+ * eds.creationDate = new Date();
+ * eds.createdBy = 'node-canopen';
+ *
+ * eds.addEntry(0x1017, {
+ *     parameterName:  'Producer heartbeat timer',
+ *     objectType:     ObjectType.VAR,
+ *     dataType:       DataType.UNSIGNED32,
+ *     accessType:     AccessType.READ_WRITE,
+ *     defaultValue:   500,
+ * });
+ *
+ * eds.save();
  */
 class Eds {
     constructor() {
@@ -927,9 +947,12 @@ class Eds {
     /**
      * Write an EDS file.
      *
-     * @param {string} path - path to file.
+     * @param {string} [path] - path to file, defaults to fileName.
      */
     save(path) {
+        if(!path)
+            path = this.fileName;
+
         const fd = fs.openSync(path, 'w');
 
         // Write header fields

diff --git a/source/protocol/emcy.js b/source/protocol/emcy.js
@@ -255,7 +255,21 @@ class EmcyMessage {
  *
  * @param {Device} device - parent device.
  * @see CiA301 "Emergency object" (§7.2.7)
- * @protected
+ * @example
+ * const can = require('socketcan');
+ *
+ * const channel = can.createRawChannel('can0');
+ * const device = new Device({ id: 0xa });
+ *
+ * channel.addListener('onMessage', (message) => device.receive(message));
+ * device.setTransmitFunction((message) => channel.send(message));
+ *
+ * device.emcy.cobId = 0x80;
+ *
+ * device.init();
+ * channel.start();
+ *
+ * device.emcy.write(0x1000);
  */
 class Emcy {
     constructor(device) {

diff --git a/source/protocol/lss.js b/source/protocol/lss.js
@@ -68,7 +68,6 @@ class LssError extends Error {
  *
  * @param {Device} device - parent device.
  * @see CiA305 "Layer Settings Services and Protocol (LSS)"
- * @protected
  */
 class Lss {
     constructor(device) {

diff --git a/source/protocol/nmt.js b/source/protocol/nmt.js
@@ -70,7 +70,21 @@ const NmtCommand = {
  *
  * @param {Device} device - parent device.
  * @see CiA301 "Network management" (§7.2.8)
- * @protected
+ * @example
+ * const can = require('socketcan');
+ *
+ * const channel = can.createRawChannel('can0');
+ * const device = new Device({ id: 0xa });
+ *
+ * channel.addListener('onMessage', (message) => device.receive(message));
+ * device.setTransmitFunction((message) => channel.send(message));
+ *
+ * device.nmt.producerTime = 500;
+ *
+ * device.init();
+ * channel.start();
+ *
+ * device.nmt.start();
  */
 class Nmt {
     constructor(device) {
@@ -234,6 +248,10 @@ class Nmt {
         if(this.producerTime == 0)
             throw TypeError('Producer heartbeat time can not be 0.')
 
+        // Switch to NmtState.OPERATIONAL
+        this.startNode();
+
+        // Start heartbeat timer
         this.timers[this.device.id] = setInterval(() => {
             this._sendHeartbeat();
         }, this.producerTime);
@@ -249,7 +267,7 @@ class Nmt {
      *
      * Change the state of NMT slave(s) to NMT state operational.
      *
-     * @param {number} nodeId - id of node or 0 for broadcast.
+     * @param {number} [nodeId] - id of node or 0 for broadcast.
      * @see CiA301 "Service start remote node" (§7.2.8.2.1.2)
      */
     startNode(nodeId) {
@@ -261,7 +279,7 @@ class Nmt {
      *
      * Change the state of NMT slave(s) to NMT state stopped.
      *
-     * @param {number} nodeId - id of node or 0 for broadcast.
+     * @param {number} [nodeId] - id of node or 0 for broadcast.
      * @see CiA301 "Service stop remote node" (§7.2.8.2.1.3)
      */
     stopNode(nodeId) {
@@ -273,7 +291,7 @@ class Nmt {
      *
      * Change the state of NMT slave(s) to NMT state pre-operational.
      *
-     * @param {number} nodeId - id of node or 0 for broadcast.
+     * @param {number} [nodeId] - id of node or 0 for broadcast.
      * @see CiA301 "Service enter pre-operational" (§7.2.8.2.1.4)
      */
     enterPreOperational(nodeId) {
@@ -285,7 +303,7 @@ class Nmt {
      *
      * Reset the application of NMT slave(s).
      *
-     * @param {number} nodeId - id of node or 0 for broadcast.
+     * @param {number} [nodeId] - id of node or 0 for broadcast.
      * @see CiA301 "Service reset node" (§7.2.8.2.1.5)
      */
     resetNode(nodeId) {
@@ -297,7 +315,7 @@ class Nmt {
      *
      * Reset communication of NMT slave(s).
      *
-     * @param {number} nodeId - id of node or 0 for broadcast.
+     * @param {number} [nodeId] - id of node or 0 for broadcast.
      * @see CiA301 "Service reset communication" (§7.2.8.2.1.6)
      */
     resetCommunication(nodeId) {
@@ -312,8 +330,16 @@ class Nmt {
      * @private
      */
     _sendNmt(nodeId, command) {
-        if(nodeId == 0 || nodeId == this.device.id)
+        if(nodeId === undefined || nodeId === this.device.id) {
+            // Handle internally and return
             this._handleNmt(command);
+            return;
+        }
+
+        if(nodeId === 0) {
+            // Broadcast
+            this._handleNmt(command);
+        }
 
         this.device.send({
             id:     0x0,

diff --git a/source/protocol/pdo.js b/source/protocol/pdo.js
@@ -17,7 +17,6 @@ const { ObjectType, AccessType, DataType, EdsError, DataObject } = require('../e
  *
  * @param {Device} device - parent device.
  * @see CiA301 "Process data objects (PDO)" (§7.2.2)
- * @protected
  */
 class Pdo {
     constructor(device) {

diff --git a/source/protocol/sdo.js b/source/protocol/sdo.js
@@ -410,7 +410,6 @@ class Queue {
  *
  * @param {Device} device - parent device.
  * @see CiA301 'Service data object (SDO)' (§7.2.4)
- * @protected
  */
 class SdoClient {
     constructor(device) {