Introduce deviceOSProtobuf.getDefinition(name) to device-os-protobuf

.circleci/config.yml

@@ -15,7 +15,7 @@ jobs:
           command: npm ci
       - run:
           name: Run tests
-          command: npm run test
+          command: npm run test:ci
       - persist_to_workspace:
           root: ~/repo
           paths: .

.eslintrc.js

@@ -0,0 +1,16 @@
+module.exports = {
+	extends: ['eslint-config-particle'],
+	parserOptions: {
+		ecmaVersion: 2018,
+		sourceType: 'module'
+	},
+	env: {
+		commonjs: true,
+		es6: true,
+		node: true,
+		mocha: true
+	},
+	rules: {
+		'max-statements': ['warn', 50]
+	}
+};

.gitignore

@@ -34,5 +34,10 @@
 # Node
 node_modules
 
+# Automated tests
+.nyc_output
+
 # Generated files
 dist/
+
+

.nvmrc

@@ -0,0 +1 @@
+12

.nycrc.json

@@ -0,0 +1,6 @@
+{
+  "branches": 100,
+  "lines": 100,
+  "functions": 90,
+  "statements":100 
+}

README.md

@@ -1,53 +1,36 @@
-# Particle Device OS Protobuf Definitions
-
-Particle devices expose Control Requests over USB and BLE for functionality like device information and Wi-Fi setup. This repo contains the definition for all these control requests in Protobuf format.
-
-<!--
-## Documentation
-
-Goal would be to have auto-generated documentation in docs.particle.io
+[![CircleCI](https://circleci.com/gh/particle-iot/device-os-protobuf/tree/main.svg?style=svg)](https://circleci.com/gh/particle-iot/device-os-protobuf/tree/main)
 
-```
-npm run build
-npm run docs
-```
-Then parse dist/index-docs.json in the Particle docs build to generate a page describing the control requests
+# Particle Device OS Protobuf Definitions
 
+Particle devices expose Control Requests over USB and BLE for functionality like device information and Wi-Fi setup. This repo contains the definition for all these control requests in Protobuf format. 
 
-Auto-generated documentation can be found at https://docs.particle.io/reference/device-os/control-requests/
+Note that most common Javascript use cases Device OS Protobuf usage over USB would be better accommodated by [particle-usb](https://github.com/particle-iot/particle-usb) rather than this project because it provides a higher level API that is easier to use and covers protobuf transmission over USB (not just encoding/decoding);
 
--->
+Device OS declares all control request IDs in [system-control.h](https://github.com/particle-iot/device-os/blob/develop/system/inc/system_control.h). Additionally, Device OS depends on `control/*.proto` files in this repo via a `git submodule`.
 
-## Node.js
+iOS and Android applications also depend on `control/*.proto` files directly via a `git submodule`.
 
-### Usage
+## Usage
+### Node.js
 
 Install package with `npm install @particle/device-os-protobuf`
 
+See [docs/reference.md](/docs/reference.md) for public api documentation
 
-```
-const proto = require('@particle/device-os-protobuf');
-const controlProto = proto.particle.ctrl;
-
-// Encode message
-const request = controlProto.GetSerialNumberRequest;
-const m = request.create({ /* GetSerialNumberRequest fields */ });
-const buf = request.encode(m).finish();
+See `src/*.test.js` files for basic usage examples.
 
-// Decode response
-const response = controlProto.GetSerialNumberReply;
-const responseObj = response.decode(data);
-```
+See `particle-usb` for production usage examples.
 
 ### Development
 
 Ensure you have installed dependencies via `npm install`.
 
 Edit the protocol buffer definitions in [`proto`](proto).
 
-Generate the JavaScript files with `npm run build`
+Generate the [protobufjs JavaScript & JSON](https://www.npmjs.com/package/protobufjs) files and markdown documentation with `npm run build`
 
-## Release
+Ensure `npm run test:ci` is passing
 
-Tag a new version with `npm version` and push `git push --follow-tags`. CircleCI will publish the package to npm.
+## Release
 
+Tag a new version with `npm version` push `git push --follow-tags`. CircleCI will publish the package to npm.

docs/reference.md

@@ -0,0 +1,170 @@
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+### Table of Contents
+
+*   [encode][1]
+    *   [Parameters][2]
+    *   [Examples][3]
+*   [decode][4]
+    *   [Parameters][5]
+    *   [Examples][6]
+*   [getDefinition][7]
+    *   [Parameters][8]
+*   [getDefinitions][9]
+*   [getNamespaces][10]
+*   [\_pbjsJSON][11]
+*   [\_pbjsObjects][12]
+*   [ProtobufDefinition][13]
+    *   [Properties][14]
+
+## encode
+
+[src/index.js:15-20][15]
+
+Create a valid Buffer of bytes that can be sent to Device, typically used with "Request" messages.
+
+### Parameters
+
+*   `protobufMessageName` **[string][16]** Protobuf message name. See getDefinitions() to valid options.
+*   `protobufMessageData` **[Object][17]** An object containing key data/code to encode & decode protobufjs messages from Device OS (optional, default `null`)
+
+### Examples
+
+Encoding a request to get serial number
+
+```javascript
+// returns a zero length Buffer because there is no properties for this message, just the option type_id
+const buffer = DeviceOSProtobuf.encode('GetSerialNumberRequest');
+```
+
+Returns **[Buffer][18]** A Buffer of bytes representing a valid protobuf message that Device OS can interpret
+
+## decode
+
+[src/index.js:34-37][19]
+
+Create a JavaScript object by decoding a Buffer representing a protobuf message from DeviceOS; typically used with "Reply" messages"
+
+### Parameters
+
+*   `protobufMessageName` **[string][16]** Protobuf message name. See getDefinitions() to valid options.
+*   `buffer` **[Buffer][18]** Buffer from DeviceOS representing valid non-decoded Protobuf message
+
+### Examples
+
+Decode a GetSerialNumberReply
+
+```javascript
+// returns a Javascript object with .serial property
+const object = DeviceOSProtobuf.decode('GetSerialNumberReply', buffer);
+// shows the serial number as a string
+console.log(object.serial);
+```
+
+Returns **[Object][17]** A JavaScript object with properties for each data item declared in the \*.proto file
+
+## getDefinition
+
+[src/index.js:43-60][20]
+
+### Parameters
+
+*   `protobufMessageName` **[string][16]** Protobuf definition from \*.proto files like "GetSerialNumberRequest". To access definitions in a namespace, prefix with "<namespace>."
+
+Returns **[ProtobufDefinition][21]** protobufDefinition An object containing code to encode & decode protobufjs messages from Device OS
+
+## getDefinitions
+
+[src/index.js:72-86][22]
+
+Returns **[Array][23]** valid strings that can be passed to getDefinition(). Includes all Request/Reply style messages as well as non request messages and enums.
+
+## getNamespaces
+
+[src/index.js:91-99][24]
+
+Returns **[Array][23]** valid dot prefixes to getDefinition() arguments (i.e. the "cellular" from "cellular".GetIccidRequest, etc)
+
+## \_pbjsJSON
+
+[src/index.js:152-152][25]
+
+Parsed JSON object generated via `npm run build:json`; this is how we get the type id associated with
+a given ctrl request
+
+## \_pbjsObjects
+
+[src/index.js:158-158][26]
+
+All of the interesting auto-generated Javascript objects from `control/*.proto` files live in this \_pbjsObjects object
+(which is keyed by protobuf message name)
+
+## ProtobufDefinition
+
+[src/index.js:72-86][27]
+
+Type: [Object][17]
+
+### Properties
+
+*   `message` **[Function][28]** protobufjs generated Javascript function that includes encode and decode methods.
+*   `id` **([number][29] | null)** integer request ID of the message for "Request" protobuf definitions, null otherwise.
+*   `replyMessage` **([Function][28] | null)** The corresponding reply message to a given "Request" message, null otherwise.
+
+[1]: #encode
+
+[2]: #parameters
+
+[3]: #examples
+
+[4]: #decode
+
+[5]: #parameters-1
+
+[6]: #examples-1
+
+[7]: #getdefinition
+
+[8]: #parameters-2
+
+[9]: #getdefinitions
+
+[10]: #getnamespaces
+
+[11]: #_pbjsjson
+
+[12]: #_pbjsobjects
+
+[13]: #protobufdefinition
+
+[14]: #properties
+
+[15]: https://github.com/particle-iot/device-os-protobuf/blob/1f7266d03f4f188fcb8f08ac910b17451eddff21/src/index.js#L15-L20 "Source code on GitHub"
+
+[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[18]: https://nodejs.org/api/buffer.html
+
+[19]: https://github.com/particle-iot/device-os-protobuf/blob/1f7266d03f4f188fcb8f08ac910b17451eddff21/src/index.js#L34-L37 "Source code on GitHub"
+
+[20]: https://github.com/particle-iot/device-os-protobuf/blob/1f7266d03f4f188fcb8f08ac910b17451eddff21/src/index.js#L43-L60 "Source code on GitHub"
+
+[21]: #protobufdefinition
+
+[22]: https://github.com/particle-iot/device-os-protobuf/blob/1f7266d03f4f188fcb8f08ac910b17451eddff21/src/index.js#L72-L86 "Source code on GitHub"
+
+[23]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[24]: https://github.com/particle-iot/device-os-protobuf/blob/1f7266d03f4f188fcb8f08ac910b17451eddff21/src/index.js#L91-L99 "Source code on GitHub"
+
+[25]: https://github.com/particle-iot/device-os-protobuf/blob/1f7266d03f4f188fcb8f08ac910b17451eddff21/src/index.js#L152-L152 "Source code on GitHub"
+
+[26]: https://github.com/particle-iot/device-os-protobuf/blob/1f7266d03f4f188fcb8f08ac910b17451eddff21/src/index.js#L158-L158 "Source code on GitHub"
+
+[27]: https://github.com/particle-iot/device-os-protobuf/blob/1f7266d03f4f188fcb8f08ac910b17451eddff21/src/index.js#L62-L67 "Source code on GitHub"
+
+[28]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[29]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number