npm package: @ssv-embedded/ssb-assembler
Description: SSV/SSB Assembler
Author: SSV Software Systems GmbH
Latest version: 1.0.0

# @ssv-embedded/ssb-assembler

This module assembles SSV/SSB fragments to packets.

## API

### assemblerFactory

```js
const {assemblerFactory} = require('@ssv-embedded/ssb-assembler');
const {createAssembler} = assemblerFactors(deps);
```

`deps` is an object for providing optional dependencies:
- `checkManId`: Is a function implementing `(manId) => valid`. It must return `true` if the given `manId` is valid. Default: `(manId) => manId === 0x0059 || manId === 0x0ad3`.
- `checkType`: Is a function implementing `(type) => valid`. It must return `true` if the given `type` is valid. Default: `(type) => type === 0x40 || type === 0x41`.
- `getTs`: Function returning the current Unix timestamp in msec. Default: `Date.now`
- `packetTimeout`: Timeout in msec for dropping incompletely received packets. Default: `5000`.

### createAssembler

```js
const assembler = createAssembler(opts);
```

Creates a new `Assembler` instance. `opts` is an object:
- `handlePacket`: Mandatory callback function: `(packet) => valid`. Is called if a full packet has been received. `packet` is an instance of `Packet`. The callback must return `true` is the received packet is valid an sequence counters should be increased.
- `getSeq`: Helper function `(senderHash) => seq` to retrieve the last seen sequence number `seq` for a given sender represented by the String `senderHash`. If the sender hasn't been seen before, this function must return `undefined`. Default: Internal in-memory sequence tracker. Won't be persisted once `assembler` is freed.
- `setSeq`: Helper function `(senderHash, seq) => {}` to set the last seen sequence number `seq` for a given sender represented by the String `senderHash`. Default: Internal in-memory sequence tracker. Won't be persisted once `assembler` is freed.

### Class: Assembler

#### Method: parseFragment(fragment)

```js
try {
	assembler.parseFragment(fragment);
} catch (err) {
	...
}
```

This call parses `fragment`. It may throw `err` if `fragment` cannot be processed. `fragment` is an object representing the received fragment:
- `address`: Mandatory. MAC address of the sending device. Format: `00:11:22:aa:dd:ff`.
- `gw`: Mandatory. MAC address of the receiving device. Format: `00:11:22:aa:dd:ff`.
- `data`: Mandatory. Hex-encoded string of the BLE advertisement frame's `Manufacturer Specific data.
- `rssi`: Optional RSSI of the advertisment frame.
- `ts`: Optional timestamp of the receiption time.

### Class: Packet

#### Properties

- `address`: Sender of the packet
- `gw`: Receiver of the fragment with the highest RSSI.
- `rssi`: Highest seen RSSI.
- `manId`: Company ID.
- `type`: Packet type.
- `seq`: Sequence number.
- `ts`: Lowest seen timestamp.
- `gwStats`: Object holding stats of all seen `gw`s.

#### Method: toBuffer()

```js
const buf = packet.toBuffer();
const manId = buf.readUInt16LE(0);
const type = buf.readUInt8(2);
const seq = buf.readUInt32LE(3);
const payload = buf.slice(7);
```

Returns the packet including its header:
- 2B Company ID `manId`
- 1B Packet Type `type`
- 4B Sequence number `seq`
- nB Payload `payload`