Signal transform documentation.

Signed-off-by: Rule Timothy (VM/EMT3) <Timothy.Rule@de.bosch.com>

doc/content/docs/arch/signalvector/index.md

@@ -13,34 +13,10 @@ github_subdir: "doc"
 
 The Dynamic Simulation Environment (DSE) presents models with a simple vector interface for the exchange of signals. Those signals can be either:
 
-- **scalar** : Internally represented as a 64bit storage container (double). These values are transparently exchanged between models, and those models may cast the values to other types (as required by the simulation designer).
-- **binary** : Binary strings (i.e. including embedded NULL characters) can be exchanged between models, and with an associated _MIME type_, complex bus simulations can be realised.
-
-
-An associated API can be used to access signal vectors:
-
-```c
-#include <dse/modelc/model.h>
-
-int model_function(ModelInstanceSpec* mi)
-{
-    SignalVector* sv = model_sv_create(mi);
-    while (sv && sv->name) {
-        for (uint i = 0; i++; i < sv->count) {
-            if (sv->is_binary) {
-                sv->reset(sv, i);
-                sv->append(sv, i, "hello world", 12);
-                printf("%s = %f (%s)\n", sv->signal[i], sv->binary[i], sv->mime_type[i]);
-            } else {
-                printf("%s = %f\n", sv->signal[i], sv->scalar[i]);
-            }
-        }
-        /* Next signal vector. */
-        sv++;
-    }
-}
-```
+- **scalar** : Internally represented as a 64bit storage container (double). These values are transparently exchanged between models. Models may cast/convert these scalar values to other types as required.
+- **binary** : Binary strings, which may container embedded NULL values, can be exchanged between models. Additionally a binary signal may be annotated with a _MIME type_ which describes the content of a binary signal.
 
+{{% alert title="Tip" color="info" %}} Binary signals with an associated MIME type may be supported by a [Network Codec]({{< relref "docs/devel/modelc_ncodec/index.md" >}}) which has an API that simplifies interactions with binary data and can be used to realise network simulations (e.g. CAN bus messaging). {{% /alert %}}
 
 
 ## Scalar Signal Vector
@@ -97,7 +73,7 @@ sv->release(sv, i);  /* Free the memory buffer of a binary signal. */
 const char* value = sv->annotation(sv, i, "name");
 ```
 
-{{% alert title="Tip" color="info" %}} Generally calling `sv->release()` is not necessary and, if avoided, will result in less memory allocation overhead during model runtime. {{% /alert %}}
+{{% alert title="Tip" color="info" %}} Using a Network Codec simplifies operations with binary signals. {{% /alert %}}
 
 
 ### Configuration
@@ -126,11 +102,101 @@ spec:
 
 
 
+## Transformations
+
+A scalar signal may be associated with a transformation by the `transform` node located alongside the `signal` node in a `SignalGroup` definition. The following transformations are supported:
+
+| Transform | Description |
+| --------- | ----------- |
+| `linear`  | S~model~ = S~vector~ * `factor` + `offset` |
+
+
+When signals are set by a model, all defined transformations are applied in the reverse direction _before_ those signal values are exchanged with other models in a simulation. Therefore a transformed signal value is only observable by a model which is associated with such a signal definition.
+
+
+### Configuration
+
+Transformations are configured for individual signals in a `SignalGroup` YAML document.
+
+**Scalar Signal Vector with Transformations :**
+```yaml
+kind: SignalGroup
+metadata:
+  name: scalar
+spec:
+  signals:
+    - signal: foo
+    - signal: bar
+      transform:
+        linear:
+          factor: 20
+          offset: -100
+```
+
+
+
+## API Examples
+
+### Using the Model API
+
+(_definied in [dse/modelc/model.h](https://github.com/boschglobal/dse.modelc/blob/main/dse/modelc/model.h)_)
+
+Signal vectors are located on the `ModelDesc` object (`model->sv`) as a NTL (Null terminated list) and can be indexed with the `model->index` function of the same object.
+
+```c
+int model_step(ModelDesc* model, double* model_time, double stop_time)
+{
+    // Find a signal using the index method.
+    ModelSignalIndex counter = model->index(m, "data", "counter");
+    if (counter.scalar == NULL) return -EINVAL;
+    *(counter.scalar) += 1;
+
+    // Find a signal vector using the index method.
+    ModelSignalIndex data_sv = model->index(m, "data", NULL);
+    if (data_sv.sv == NULL) return -EINVAL;
+
+    ...
+}
+```
+
+### Using the Runtime API
+
+(_definied in [dse/modelc/runtime.h](https://github.com/boschglobal/dse.modelc/blob/main/dse/modelc/runtime.h)_)
+
+The Runtime API can be used to access signal vectors and is of particular use to tool developers and integrators who need access to runtime objects.
+
+```c
+#include <dse/modelc/model.h>
+
+int model_function(ModelInstanceSpec* mi)
+{
+    SignalVector* sv = model_sv_create(mi);
+    while (sv && sv->name) {
+        for (uint i = 0; i++; i < sv->count) {
+            if (sv->is_binary) {
+                sv->reset(sv, i);
+                sv->append(sv, i, "hello world", 12);
+                printf("%s = %f (%s)\n", sv->signal[i], sv->binary[i], sv->mime_type[i]);
+            } else {
+                printf("%s = %f\n", sv->signal[i], sv->scalar[i]);
+            }
+        }
+        /* Next signal vector. */
+        sv++;
+    }
+}
+```
+
+
+
 ## References
 
 * [dse/modelc/model.h](https://github.com/boschglobal/dse.modelc/blob/main/dse/modelc/model.h) - definition of Signal Vector API.
 * [SignalGroup](https://github.com/boschglobal/dse.schemas/blob/main/schemas/yaml/SignalGroup.yaml) schema definition.
 * DSE Model C examples:
     * [Binary Model](https://github.com/boschglobal/dse.modelc/tree/main/dse/modelc/examples/binary)
-    * [Gateway Model](https://github.com/boschglobal/dse.modelc/tree/main/dse/modelc/examples/gateway)
-* [Frame Stream Interface (Automotive Bus)](https://github.com/boschglobal/automotive-bus-schema/blob/main/schemas/stream/frame.fbs) with [sample](https://github.com/boschglobal/automotive-bus-schema/tree/main/examples/streams) code.
+    * [NCodec Model](https://github.com/boschglobal/dse.modelc/tree/main/dse/modelc/examples/ncodec)
+    * [Transform Model](https://github.com/boschglobal/dse.modelc/tree/main/dse/modelc/examples/transform)
+* Binary Codecs:
+    * [Network Codec]({{< relref "docs/devel/modelc_ncodec/index.md" >}}) from DSE Model C which implements a stream interface to the Network Codec API by using binary signals and associated MIME type annotations.
+    * [Network Codec API](https://github.com/boschglobal/dse.standards/tree/main/dse/ncodec) generalised codec library with an example binary stream implementation.