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

[joegoggins]

Overview

Introduces main public API methods for this module:

• encode(protobufMessageName, {data: "foo"})
• decode(protobufMessageName, buffer)
• getDefinition(protobufMessageName)
• getDefinitions() / getNamespaces()

Story details: https://app.shortcut.com/particle/story/95530

How to test?

1. git checkout sc-95530/introduce-getDefinition-function
2. npm i
3. npm run test:ci; observe linter, tests, and coverage stats.
4. Read the README.md; note anywhere things could be written more clearly.
5. Read the rendered docs/reference.md; ask questions if anything isn't clear.

[joegoggins]

While critically reviewing this PR myself, I decided to read the entire README of the protobufjs to understand if we are using this module correctly.

One aspect of our technical approach is odd.

We use both npm build / pbjs -o static-module (for generated js code) and npm build:json / pbjs -o json (for the mapping to request id). This choice was made without considering the protobuf.load("awesome.proto".../reflection option which can reflect on *.proto files at runtime rather than via pre-generated code. If this worked, that approach would eliminate these 2 build steps.

I'm not proposing we pursue that now because I think this PR is a good step forward. But wanted to raise the option in case others wanted to chime in.

[monkbroc]

Looks good at a glance. I haven't run the library directly.

[monkbroc]

We use both npm build / pbjs -o static-module (for generated js code) and npm build:json / pbjs -o json

I'd say run both variants of the pbjs command with one npm run build

[joegoggins]

Cool. Thanks for the feedback @monkbroc , I've pushed commits that address all of your comments/questions.

@sergeuz I'm looking forward to your feedback as well.

One thing I forgot to mention earlier was this snippet of code inside particle-usb (see experimental branch) that demonstrates how low level API (sendProtobufRequest) vs high level API (getSerialNumber) will operate with this getDefinition() construct from the new sendProtobufRequest method we'll introduce there. I'm into it, that PR review should be coming along shortly.

async function main() {
    const particleUSB = require('./src/particle-usb');
    const devices = await particleUSB.getDevices();
    const device = devices[0];
    await device.open();
    const serialNumberHighLevelAPI = await device.getSerialNumber();
    console.log('serialNumberHighLevelAPI', serialNumberHighLevelAPI);

    const serialNumberLowLevelAPI = await device.sendProtobufRequest(
        'GetSerialNumberRequest',
        null,
        {timeout: 7000}
    )
    console.log('serialNumberLowLevelAPI', serialNumberLowLevelAPI.serial);

    await device.close();
}

main();

[monkbroc]

Nice 👍

[monkbroc]

Looks great now!