senseBox sketch-templater
Arduino sketch templates used by the openSenseMap-API. The sketch-templater
creates a Arduino Sketch (.ino
) for the Arduino IDE based on the selected options and sensors during the registration process on openSenseMap.
Versioning
The version of templates should always match the corresponding Version of the Board Support Package
Changelog
See CHANGELOG.md
Releasing a new version
To create a new version, use npm version
.
- Document your changes in
CHANGELOG.md
. Make sure there are no uncommited changes in the worktree. - Run
npm version [major | minor | patch] -m "[v%s] Your commit message"
- Type in the new version (to create a
beta
release include the wordbeta
in the new version) git push --tags origin main
npm publish
Usage
Install via npm install --save @sensebox/sketch-templater
or yarn add @sensebox/sketch-templater
const Sketcher = require('@sensebox/sketch-templater');
const mySketcher = new Sketcher('<your api post domain>');
// generate Sketch
const mySketch = mySketcher.generateSketch(box);
const mySketchBase64 = mySketcher.generateSketch(box, { encoding: 'base64' });
Configuration
In order to fill in the correct ingress domain, you have to specify a valid hostname. Do not specify a protocol (http or https)!
You can do this either in code when calling the new Sketcher('your domain here')
or through external configuration.
If your project is using lorenwest/node-config
, you can specify the ingress domain in your config file of your project like this:
{
... your other config
"sketch-templater": {
"ingress_domain": "ingress.example.com"
}
}
Adding new Templates
To add new templates, just create a new .tpl
file in the templates
directory. A template consists of two parts. The first line contains a JSON object for configuration. The second line until the end is used as the template text.
Example configuration in first line
Specify a single model:
{ "model": "homeEthernet" }
Specify multiple models:
{ "models": ["homeWifi", "homeWifiFeinstaub"] }
Templating values
The templater uses special transformers to process the templates. The transformers are applied through searching for @@SUB_TEMPLATE_KEY@@
occurrences in the template files. Each replacement starts and ends with a double @
. To specify a transformer, append a pipe (|
) and the transformer name. When no transformer is specified, it just returns the input variable. For adding new template transformers, see Adding Transformers.
As of writing this, the following replacements can be made:
Template text | Replacement |
---|---|
@@SENSEBOX_ID@@ |
the senseBox ID |
@@SENSEBOX_NAME@@ |
the senseBox Name |
@@SENSOR_IDS@@ |
sensor IDs |
@@NUM_SENSORS@@ |
the number of sensors |
@@INGRESS_DOMAIN@@ |
the domain of your ingress server |
@@SERIAL_PORT@@ |
Serial port for connected SDS011 (only Feinstaub models) |
@@SSID@@ |
your WiFi SSID (only homeV2Wifi models) |
@@PASSWORD@@ |
your WiFi Password (only homeV2Wifi models) |
@@ACCESS_TOKEN@@ |
the access_token of wifi / ethernet boxes |
Additionally, the following transformers are implemented:
Transformer name | Description |
---|---|
as-is |
Do nothing. |
toDefine |
Transform an array of sensors to multiple #define statements. |
toProgmem |
Transform an array of sensors to multiple const char xxSENSOR_ID[] PROGMEM = "<id>"; statements. |
digitalPortToPortNumber |
Transform a digital port (A , B or C ) to a port number. You can add a offset parameter. |
Adding Transformers
In order to add a new transformer, just add a function in src/transformers.js
to the module.exports
. The function should return a string.
Adding Replacements
Add your additional replacements in src/index.js
in the method _cloneBox
to the second parameter of the Object.assign
call.