cbuslibrary

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>JSDoc: Home</title> <script src="scripts/prettify/prettify.js"> </script> <script src="scripts/prettify/lang-css.js"> </script>  <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> </head> <body> <div id="main"> <h1 class="page-title">Home</h1> <h3> </h3> <section> <article><h1>cbusLibrary</h1> <h3>Library for decoding and encoding CBUS Layout Control Bus (LCB) messages, including extended messages used for firmware download</h3> <p>There is a very comprehensive set of tests for this - see <strong>tests</strong> section further below. <br> The decoding and encoding of standard (11 bit) CAN ID messages follows the CBUS specification available here <a href="https://www.merg.org.uk/merg_wiki/doku.php?id=public:cbuspublic:developerguide">CBUS dev guide</a><br> At the time of writing, there isn't a formal definition of extended (29 bit) CAN ID message formats, so the methods are based on current implementations</p> <h3>Full API details available <a href="cbusLibrary.html">here</a></h3> <h2>Installation</h2> <pre><code>npm install cbuslibrary </code></pre> <p>(note all lower case - npm no longer allows uppercase)</p> <h2>Usage</h2> <pre><code>const cbusLib = require('cbusLibrary') </code></pre> <p>An instance of the class is created automatically, so can be used immediately</p> <h2>General information</h2> <h3>decoding</h3> <p>for decoding, there's one common function (as the opcode is embedded in the message) var cbusMsg = cbusLib.decode(<message to be decoded>)</p> <p>The decode function returns a collection of values, with "encoded", "ID_TYPE" and "text" being standard for all messages See an expanded description of 'eventName' further below</p> <p>example CBUS (11 bit Id) message decode:</p> <pre><code>{ "encoded": ":SB780ND200010000FF00;", "ID_TYPE":"S", "mnemonic": "EVLRN", "opCode": "D2", "nodeNumber": 1, "eventNumber": 0, "eventName": "00010000", "eventVariableIndex": 255, "eventVariableValue": 0, "text": "EVLRN (D2) nodeNumber 1 eventNumber 0 eventName 00010000 Event Variable Index 255 Event Variable Value 0" } </code></pre> <p>Note that some properties have full names to avoid confusion (e.g. eventVariableIndex, rather than EV#)</p> <p>example extended (29 bit Id) message decode:</p> <pre><code>{ "encoded":":X00080004N000000000D040000;", "ID_TYPE":"X", "operation":"PUT", "type":"CONTROL", "address":"000000", "RESVD":0, "CTLBT":13, "SPCMD":4, "CPDTL":0, "CPDTH":0 "text": {"encoded":":X00080004N000000000D040000;","ID_TYPE":"X","operation":"PUT","type":"CONTROL","address":"000000","RESVD":0,"CTLBT":13,"SPCMD":4,"CPDTL":0,"CPDTH":0} } </code></pre> <h3>encoding</h3> <p>For encoding standard CBUS messages, there's one function encode() thats takes a JSON object, which needs the 'mnemonic' for the specific opcode, and any parameters the opcode requires<br> The format of the JSON object follows exactly the same syntax as the result from the decode() function above<br> Each opcode also it's own function, that has individual parameters, as the type & number of parameters vary with opCode</p> <ul style="list-style-type:none;"><li>var encode = cbusLib.encodeEVLRN(nodeNumber, eventNumber, VariableIndex, eventVariableValue);</li></ul> <p>There are only separate functions for encoding extended CBUS messages currently</p> <h3>eventIdentifier</h3> <p>An event is identified by 4 bytes made up from either the node number plus the event number in the case of a 'long' event, or in a 'short' event just the 2 byte device number (with the top bytes set to zero)<br> The 'eventIdentifier' is used to provide the correct value depending on the type of event ('long' or 'short'), in an 8 digit hexadecimal string with leading zero's<br> i.e.<br> 'long' event = node number + event number<br> 'short' event = 0000 + device number<br> <br> The command 'ENRSP' also expects this four byte 'eventIdentifier' as a parameter as well as the node number<br></p> <h3>CAN header (11 bit CAN identifier)</h3> <p>There are default values for the 11 bit CAN header used when encoding messages, but these can be changed using the following function</p> <ul style="list-style-type:none;"><li>setCanHeader(MjPri, CAN_ID)</li></ul> <p>Once set, the new values will continue to be used for subsequent encodes (or until the program is restarted)<br></p> <p>Note that MinPri is specifically defined for each opCode, so is set for each individual opCode and not expected to be changed</p> <h3>CAN header (29 bit CAN identifier)</h3> <p>The absence of a definition for the 29 bit identifier means that the identifier is hard coded to match existing</p> <ul style="list-style-type:none;"> <li>0000N000&ltA&gt for FCU originated messages</li> <li>8000N000&ltA&gt for module originated messages</li> </ul> where: &ltA&gt is a bit mapped character, bit 0 being control/data, and bit 1 being put/get <h2>Tests</h2> <p>There is a comprehensive suite of unit tests for all the message decode/encodes, which also create a log file</p> <h3>How to run all tests</h3> <ul style="list-style-type:none;"><li>npm test</li></ul> Will run al the tests - note there are more than 27,000 tests, and although doesn't take too long, it does create a huge log file <h3>How to run specific test</h3> <p>You can also run a specific test, which produces a much more workable log file</p> <ul style="list-style-type:none;"><li>npm test -- --grep "EVLRN"</li></ul> <h3>Tests log file</h3> <p>For all tests, the log file is created in /tests/logs, and is overwritten on each test run</p> <h2>Documentation</h2> <p>The project uses JSDocs to generate most of the documentation</p> <h3>How to run jsdoc</h3> <ul style="list-style-type:none;"><li>npm run jsdoc</li></ul> This creates the documents in the 'out' folder, and are copied manually in the root project directory when finalised</article> </section> <section> <header> <h2>cbuslibrary.js</h2> </header> <article> <div class="container-overview"> <div class="description"><strong>Module to decode & encode CBUS message strings</strong></br></div> <dl class="details"> <dt class="tag-source">Source:</dt> <dd class="tag-source"><ul class="dummy"><li> <a href="cbuslibrary.js.html">cbuslibrary.js</a>, <a href="cbuslibrary.js.html#line3">line 3</a> </li></ul></dd> </dl> </div> </article> </section> </div> <nav> <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="cbusLibrary.html">cbusLibrary</a></li></ul> </nav> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Mon Nov 07 2022 18:56:05 GMT+0000 (Greenwich Mean Time) </footer> <script> prettyPrint(); </script> <script src="scripts/linenumber.js"> </script> </body> </html>