ardunno-cli-gen

Generates nice-grpc API for the Arduino CLI from the proto files

Installing

npm i ardunno-cli-gen -S

Usage

CLI

Usage: ardunno-cli generate [options] <src>

Generates TS/JS API for the Arduino CLI

Arguments:
  src                 The source of the proto files to generate from.
                      The input source can be a path to the folder
                      which contains the proto files. The source can be
                      a valid semver. Then, the proto files will be
                      downloaded from the Arduino CLI's GitHub release.
                      It can be a GitHub commit in the following format
                      `(?<owner>)/(?<repo>)(#(?<commit>))?`. Then, the
                      proto files will be cloned and checked out from
                      GitHub.

Options:
  -o, --out <string>  Specify an output folder for all emitted files.
  -f, --force         Override previously emitted files in the output
                      location.
  -h, --help          display help for command

Examples:

# generates from local proto files
npx ardunno-cli generate ./path/to/rpc --out ./src-gen

# generates from a valid semver
npx ardunno-cli generate 0.29.0 --out ./src-gen

# generates from the HEAD of the default branch
npx ardunno-cli generate arduino/arduino-cli --out ./src-gen

# generates from a specific commit
npx ardunno-cli generate arduino/arduino-cli#5a4ffe0 --out ./src-gen

# generates from a specific branch of a fork
npx ardunno-cli generate cmaglie/arduino-cli#alternate-homedir --out ./src-gen

API

CommonJS:

const { generate } = require('ardunno-cli-gen');

TypeScript:

import { generate } from 'ardunno-cli-gen';

Generate:

// `src` is a path like, a valid semver or a GitHub ref as `(?<owner>)/(?<repo>)(#(?<commit>))?`
// `out` is the output folder
// user `force` if you want to override the generated output
await generate({ src: '0.29.0', out: './src-gen', force: true });

Running the tests

npm run test

Using

• nice-grpc - A TypeScript gRPC library that is nice to you
• ts-proto - An idiomatic protobuf generator for TypeScript
• protobufjs - Protocol Buffers for JavaScript (& TypeScript)
• protoc - A simple wrapper for the protoc

Notes

• The underlying protoc version is 3.20.3. It comes from the protoc dependency. protoc is not required on the $PATH

  npx protoc --version
  libprotoc 3.20.3

• Use debug to log additional details

  % DEBUG=ardunno-cli* npx ardunno-cli generate ./path/to/rpc --out ./src-gen
    ardunno-cli-gen generating with {"src":"./path/to/rpc","out":"./src-gen","force":false} +0ms
    ardunno-cli-gen accessible ./src-gen +2ms
    ardunno-cli-gen glob ./path/to/rpc +1ms
    ardunno-cli-gen accessible ./path/to/rpc +1ms
  [...]

• Run the generator from the sources (or use the predefined generate VS Code task):

  • npm run compile
  • `node dist/cli.js generate 0.32.2 --out ./gen-output

License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

The Arduino CLI, including the proto files, has a GPL-3.0 license. ardunno-cli-gen does not use any code from the CLI but relies on the proto files. There is an ongoing conversation with Arduino to relicense the proto files with a more permissive license, such as MIT. Please open a new issue if you have any concerns regarding the licensing of this project. Thank you!

I made ardunno-cli-gen with pure ❤️

Acknowledgments

• @per1234 for the tireless support on the Arduino Forum