From b391afe121c5594f75b32652eed3337a10f93ca8 Mon Sep 17 00:00:00 2001 From: derwehr Date: Tue, 2 Jan 2024 13:03:57 +0100 Subject: [PATCH 1/3] docs: add `octet-stream` codec documentation --- packages/core/README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/packages/core/README.md b/packages/core/README.md index b77bc588e..d9d040578 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -21,6 +21,37 @@ see binding examples such as - https://github.com/eclipse-thingweb/node-wot/blob/master/packages/binding-http - https://github.com/eclipse-thingweb/node-wot/blob/master/packages/binding-coap +## Codecs + +### Octet-Stream +The octet-stream codec enables deserialization and serialization of binary data. To encode and decode sequences of bytes, the octet-stream codec uses the following content type parameters: +| Parameter | Description | Default | +| --- | --- | --- | +| `length` | Number of bytes produced during serialization or consumed during deserialization | | +| `signed` | Signedness of the data type, `true` or `false` | `true` | +| `byteSeq` | Endianness, enum of `BIG_ENDIAN`, `LITTLE_ENDIAN`, `BIG_ENDIAN_BYTE_SWAP`, `LITTLE_ENDIAN_BYTE_SWAP` | `BIG_ENDIAN` | + +Additionally, the octet-stream codec supports the data schema terms below for addressing bit-fields: +| Term | Description | Default | +| --- | --- | --- | +| `ex:bitLength` | Number of bits produced during serialization or consumed during deserialization | | +| `ex:bitOffset` | Offset in bits from the beginning of the byte sequence | `0` | + +With the help of the terms and parameters above, the octet-stream codec can be used to serialize and deserialize objects containing bit-fields and sequences of bytes, like in the following example. + +#### Example +To serialize the object `{ flag1: true, numberProperty: 99, stringProperty: "Web" }` to a sequence of bytes, the content type `application/octet-stream;length=4;signed=false;`, along with the following data schema can be used: +```json +{ + "type": "object", + "properties": { + "flag1": { "type": "boolean", "ex:bitOffset": 0, "ex:bitLength": 1 }, + "numberProperty": { "type": "integer", "ex:bitOffset": 1, "ex:bitLength": 7 }, + "stringProperty": { "type": "string", "ex:bitOffset": 2, "ex:bitLength": 24 }, + }, +} +``` + ## More Details See From bb7de5bad5658d838d86875e9e4fc592dda566bc Mon Sep 17 00:00:00 2001 From: derwehr Date: Sun, 7 Jan 2024 17:06:00 +0100 Subject: [PATCH 2/3] fix: statisfy prettier --- packages/core/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/packages/core/README.md b/packages/core/README.md index d9d040578..22cd00daa 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -24,6 +24,7 @@ see binding examples such as ## Codecs ### Octet-Stream + The octet-stream codec enables deserialization and serialization of binary data. To encode and decode sequences of bytes, the octet-stream codec uses the following content type parameters: | Parameter | Description | Default | | --- | --- | --- | @@ -40,15 +41,17 @@ Additionally, the octet-stream codec supports the data schema terms below for ad With the help of the terms and parameters above, the octet-stream codec can be used to serialize and deserialize objects containing bit-fields and sequences of bytes, like in the following example. #### Example + To serialize the object `{ flag1: true, numberProperty: 99, stringProperty: "Web" }` to a sequence of bytes, the content type `application/octet-stream;length=4;signed=false;`, along with the following data schema can be used: + ```json { "type": "object", "properties": { "flag1": { "type": "boolean", "ex:bitOffset": 0, "ex:bitLength": 1 }, "numberProperty": { "type": "integer", "ex:bitOffset": 1, "ex:bitLength": 7 }, - "stringProperty": { "type": "string", "ex:bitOffset": 2, "ex:bitLength": 24 }, - }, + "stringProperty": { "type": "string", "ex:bitOffset": 2, "ex:bitLength": 24 } + } } ``` From 7dd808d04084441aade6067a3d2fe546043a68aa Mon Sep 17 00:00:00 2001 From: Thomas Wehr Date: Mon, 8 Jan 2024 10:56:53 +0100 Subject: [PATCH 3/3] fix: adjust bit offset Co-authored-by: danielpeintner --- packages/core/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/core/README.md b/packages/core/README.md index 22cd00daa..98ba83818 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -50,7 +50,7 @@ To serialize the object `{ flag1: true, numberProperty: 99, stringProperty: "Web "properties": { "flag1": { "type": "boolean", "ex:bitOffset": 0, "ex:bitLength": 1 }, "numberProperty": { "type": "integer", "ex:bitOffset": 1, "ex:bitLength": 7 }, - "stringProperty": { "type": "string", "ex:bitOffset": 2, "ex:bitLength": 24 } + "stringProperty": { "type": "string", "ex:bitOffset": 8, "ex:bitLength": 24 } } } ```