leap-protocol

• Specification documentation

L3aP for Javascript

Legible encoding for addressable packets for javascript

Installation

npm install leap-protocol

Basic Usage

Encoding a packet:

const fs = require(fs);
const leap = require('leap-protocol');

const config = JSON.parse(fs.readFileSync('leap-config.json'));
const codec = new leap.Codec(config);
const packet = new leap.Packet("set", "led/red", true);
const encoded = codec.encode(packet);

...

Decoding a packet:

const fs = require(fs);
const leap = require('leap-protocol');

const config = JSON.parse(fs.readFileSync('leap-config.json'));
const codec = new leap.Codec(config);

...
// Note: if there is a remainder it will be stored back in bytes
const [received, packets] = codec.decode(received);
const data = codec.unpack(packets[0]);

Object.keys(data).forEach(function (address) {
  // data[address] are the values in the unpacked data
  // address provides the full string path of data. e.g. led/red
  ...
});

Usage

Codec Class

codec = Codec(config)

• config L3aP configuration object.
• codec L3aP codec object

Instantiates a L3aP codec object for encoding packets to strings and decoding strings to packets.

Example:

const config = yaml.parse(fs.readFileSync("leap-protocol.yaml"));
const codec = new leap.Codec(config);

is_valid = valid()

• is_valid returns true or false

Determines whether the codec has a valid configuration. If the config is not valid, the codec cannot be used.

Example:

...
const codec = new leap.Codec(config);
if (codec.valid()) {
  ...
}

bytes = encode(packets)

• packets either a leap.Packet object or a list of leap.packet objects.
• bytes utf-8 byte string

Encodes one or more packets into a utf-8 byte string.

Example:

const packet_red = new leap.Packet("set", "led/red", true);
const packet_blue = new leap.Packet("set", "led/blue", true);

encoded = codec.encode([packet_red, packet_blue]);

(remainder, [packets]) = decode(bytes)

• bytes utf-8 encoded byte-string
• remainder unused bytes (if available)
• packets an array of one or more decoded packets, empty if none

Decodes a utf-8 byte string into one or more packets

Example:

const received_bytes += rx.read();
const [received_bytes, packets] = codec.decode(received_bytes);

for (packet of packets) {
  ...
}

data = unpack(packet)

• packet a leap.Packet
• data an object with address paths as keys (eg. led/red) mapping to thier respective values.

Extracts a dictionary from a packet to map address paths to thier respective values.

Example:

if (packet.category === "set") {
  const commands = codec.unpack(packet);
  if ('led/red' in commands) {
    led_red.set(commands['led/red']);
    ...
  }
  ...
}

Packet Class

packet = Packet(category, path, payload)

• category the type of packet
• path (optional) a root path of payload data, set to null if not required
• payload (optional) the data to accompany the root path, set to null if not required
• packet a L3aP packet object

Constructs a L3aP packet for encoding. Note, payload can be an array and will set multiple fields at once when the path is a parent.

Example:

const accelerometer_packet = new leap.Packet("pub", "imu/accel", [accel_x, accel_y, accel_z]);
const disable_packet = new leap.Packet("set", "control/balance/disable");
...

add(path, payload)

• path a root path of payload data
• payload (optional) the data to accompany the root path, set to null if not required

Adds path to the packet and optionally a payload. This can be used to create compound packets which allows sets of data to be processed at the same time.

Example:

const sensor_packet = new leap.Packet("pub", "imu/accel", [accel_x, accel_y, accel_z]);
sensor_packet.add("barometer/pressure", baro_pressure);
...

category

The packet's category string.

Example:

if (packet.category === "pub") {
  update_model(codec.unpack(packet));
}
...

Accessing packet data

See the codec.unpack(packet) method above.

Verification

result = verify(config_file)

• config_file a L3aP config object
• result false if config is invalid, true otherwise

Checks the contents of a config object for errors. Prints details of the first failure to stdout. Useful for regression testing.

Example:

...
function test_valid_config(self) {
  const config = yaml.parse(fs.readFileSync("../leap-protocol.yaml"));
  assert(leap.verify(config);
}
...

Command Line

A command line tool is avaliable for L3aP:

npm install leap-cli -g

Generate a default config file:

leap generate filename

File names can have extension .yaml .json or .toml.

Verify the contents of your config file:

leap verify configfile

Files can have extension .yaml .json or .toml.

Encode a packet based on a config file:

leap encode configfile category address --payload payload

Example:

hoani@Hoani-CPU sandbox % leap encode config.yaml set item-1/child-1 1 --payload 10 1024.125
Encoded Packet ( set, item-1/child-1, [10,1024.125]):
S0001:0a:44800400

Decode a packet based on a config file:

leap decode configfile packet

Example:

hoani@Hoani-CPU sandbox % leap decode config.yaml S0001:0a:44800400
Decoded Packet <S0001:0a:44800400>:
   category - set
   address "item-1/child-1/grand-child-1" = 10
   address "item-1/child-1/grand-child-2" = 1024.125

Help:

leap --help