Resources

Configuration of resources "resources"

There are certain functions that require a supplementary static configuration in addition to their dynamic function parameters. These are, for example, lookup tables or control technology functions with register widths or counting ranges. This static configuration is passed to the function call as the last parameter in the form of a JSON object.

The configuration directly at the function call is still useful for a few individual parameters; for extensive configurations, e.g. a classification or a filter, these resources can be outsourced to a separate area in the math module for better readability of the formula set. Outsourcing also allows the same configuration to be reused in different places in the formula set.

It is possible within the framework of so-called resources,

store text for configuration or further processing,
to outsource complex JSON objects from the formula set to a designated area of the configuration and
to enable the processing of any data (text or binary) using so-called decoders.

These resources are initialized ONCE at the start of measurement mode and can be configured as follows

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {

    ...

    "resources": {
      "someTextResource": [

          < LINES OF TEXT >

      ],
      "someObjectResource": {

          < JSON STYLE Configuration >

      },
      "someDecodableResource": {
        "decoder": [

          < DECODERS >

        ],
        "value": "someInitialResourceValueString"
      }
      ...
    }
  }
}

We distinguish here between

Pure text resources that specify the text similar to the math parameter as a single string or a list of strings (in the form of a JSON array). The individual strings in the list are joined using '\n' before use. (in the above example someTextResource)

Object resources, which provide displayable JSON objects for configuring functions in the formula text (in the above example someObjectResource)
and decodable resources, which apply a sequence of processing operations (decoders) one after the other to an initial data packet and also provide the result as a data packet (in the above example someDecodableResource). This data packet can be a readable text but also a binary data packet.

Access to and conversion of resources

Resources can be accessed only at the location of the last parameter of a function that accepts a JSON object as a parameter

someJsonObjectAcceptingFunction( ... , {$ref:'someResource'} )

and typically returns a JSON object. An exception is, for example, the lookup() function, which expects a text block with a proprietary data header and a sequence of data values from the resource to fill the table.

However, if a string representation is expected, the content of the resource can be converted as follows

someStringAcceptingFunction( ... , sResource({$ref:'someResource'}), ... )

In any case, it is the user's responsibility to provide data in such a way that the function or formula set used can also interpret and process the data.

Example: Provision of a text-based configuration from a text resource:

In the following example, the configuration of a lookup table in the form of a proprietary text format is expected. The individual data points follow the header rows.

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {
    "math": "someTextAcceptingFunction( ... , {$ref:'someText'} );",
    "resources": {
      "someText": [
          "IN kPa 0.0 0.167751 161"
        , "OUT l"
        , ""
        , "0"
        , "42.942"
        , "87.924"
        , "134.946"
        , "184.008"
        , "235.11"
        , "288.252"
        , "343.434"
        , "400.656"
        , "459.918"
        , "521.22"
        , "584.562"
        , "..."
      ],
      ...
    }
  }
}

Further application examples could be

A predefined e-mail text for notification, in which text markers are replaced by concrete values in the formula set.
An XML structure for a subsystem that must be configured for a measurement task.

Example: Provision of an expected JSON object from an object resource

In the following example, a static function configuration in the form of a JSON object is expected

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {
    "math": "someObjectAcceptingFunction( ... , { someParam: value } );"
  }
}

This can be provided by an object resource as follows

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {
    "math": "someObjectAcceptingFunction( ... , {$ref:'someObject'} );",
    "resources": {
      "someObject": {
        someParam: value
      },
      ...
    }
  }
}

Example: Provision of a processed character string from resources

In the following example, the function "someObjectAcceptingFunction" expects a processed string (such as the content of a file or a decoded or unpacked representation of the string, see section "decoder" for more details).

This can be realized by a decodable resource as follows

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {
    "math": "someObjectAcceptingFunction({$ref:'someDecodableResource'});",
    "resources": {
      "someDecodableResource": {
        "decoder": [
          "someFirstDecoderStage someFirstFirstDecoderArgument ... someLastFirstDecoderArgument",
          ...,
          "someLastDecoderStage someFirstLastDecoderArgument ... someLastLastDecoderArgument"
        ],
        "value": "someInitialStringValue"
      }
    }
  }
}

Here, the first decoder stage "someDecoderStageFIRST" first converts the initial string value of the resource "someInitialValueString" into an intermediate result and all subsequent decoder stages calculate the following intermediate result from the previous intermediate result, with the last decoder stage returning its intermediate result as the final result in the form of a JSON value of type String.

Note: If this result is to be used where a string is expected, it must be converted using "sResource" when it is accessed, as described above.

Decoding of resources "decoder"

The task of a decoder is to convert a source string into a target string.

The following decoders are currently available

file for reading in a file
base64 for decoding a base64-formatted string
unzip for unpacking the contents of a gzip-packed file

Furthermore, a very flexible decoder

system for calling system processes

Decoder "file"

The "file" decoder is used to read in a file "/sdi/config/some/file/name", as follows

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {
    "math": "someJsonValueAcceptingFunction({$ref:'someFileResource'});",
    "resources": {
      "someFileResource": {
        "decoder": [
          "file"
        ],
        "value": "some/file/name"
      }
    }
  }
}

If a relative path is specified as the "value" of the decoder, this addresses relative to the smartCORE configuration directory /sdi/config/. However, an absolute path can also be specified.

Decoder "unzip"

The "unzip" decoder can be used to unzip gzip-packed files, e.g. as follows

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {
    "math": "someJsonValueAcceptingFunction({$ref:'someFileResource'});",
    "resources": {
      "someFileResource": {
        "decoder": [
          "file",
          "unzip"
        ],
        "value": "some/compressed/file/name.gz"
      }
    }
  }
}

Decoder "base64"

The "base64" decoder can be used to decode base64-encoded files, e.g. as follows

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {
    "math": "someJsonValueAcceptingFunction({$ref:'someFileResource'});",
    "resources": {
      "someFileResource": {
        "decoder": [
          "file",
          "base64"
        ],
        "value": "some/base64/encoded/file.b64"
      }
    }
  }
}

Decoder "system"

The "system" decoder can be used to initialize resources using any system calls. This supports call parameters. Example:

{
  "module": "math1",
  "factory": "mathmodule",
  "config": {
    "math": "someJsonValueAcceptingFunction({$ref:'someEditedResource'});",
    "resources": {
      "someEditedResource": {
        "decoder": [
          "file",
          "system sed -e 's/hello/world/g'"
        ],
        "value": "some/source/file"
      }
    }
  }
}

Configuration of resources "resources"​

Access to and conversion of resources​

Example: Provision of a text-based configuration from a text resource:​

Example: Provision of an expected JSON object from an object resource​

Example: Provision of a processed character string from resources​

Decoding of resources "decoder"​

Decoder "file"​

Decoder "unzip"​

Decoder "base64"​

Decoder "system"​