JSON Configuration Format - heros-boss 0.6.10 documentation

Skip to content
Back to top
View this page

# JSON Configuration Format

This page describes the JSON configuration format for HERO devices. The JSON configuration can be provided as a single HERO config object or as a collection of HERO configs under the `rows` key.

## Single HERO Config

A single HERO config is a dictionary with the following keys:

    {
        "_id": "hero_name",
        "classname": "module.class",
        "arguments": {},
        "extra_decorators": {},
        "datasource": {}
    }

Key | Type | Description
--- | --- | ---
`_id` | string | Name of the HERO.
`classname` | string | Path to the device driver class in the form `module.class`.
`arguments` | dict | Dictionary of keyword-value pairs passed to the `__init__` function of the class specified in `classname`.
`extra_decorators` | dict | Dictionary of keyword-value pairs of method name and list of decorator paths.
`datasource` (optional) | dict | Keyword-value pairs that describe a datasource (classes with the `observable_data` function).
`tags` (optional) | list | List of tags that are added to the HERO. The tag `BOSS: {name_of_boss}` is always added to the tag list independent of this configuration.
`wrap_target` (optional) | string | Controls wrapping of the target class for compatibility with external driver libraries. Default is auto detected. More info.

## Special Arguments

    {
        "_id": "hero_name_1",
        "classname": "module.class",
        "arguments": {
            "loop": "@_boss_loop",
            "some_object": "$remotehero_name"
        }
    }

### Event Loop

Using `@_boss_loop` as the value of the key/value pair in the `arguments` part of the configuration passes the `asyncio.EventLoop` which is running inside `BOSS`. Note, `asyncio` support in Zenoh is still in development and using the event loop might not behave as expected.

### RemoteHEROs

Sometimes a HERO needs to act on another HERO in the network. BOSS allows to specify a reference to another hero by giving the name of the HERO with the magic prefix `$`. When a string with this magic prefix is found, BOSS tries to build a RemoteHERO object from the given HERO name and passes the RemoteHERO into the constructor of the object to be built. To account for situations where the HERO is not yet available, BOSS tries several times (default 10 times) to create the RemoteHERO with the given name.

## Extra Decorators

The `extra_decorators` can be used to add decorators to methods during the creation of the HERO.

    {
        "_id": "hero_name_1",
        "classname": "module.Class",
        "extra_decorators": [
            ["some_data", "heros.event"],
            ["_hidden method", "heros.inspect.force_remote"],
            ["foo_bar", "some.module.decorator"],
            ["method", "some.other_module.decorator2"]
        ]
    }

In this example, the method `module.Class.some_data` will become an event in the HEROS network. The method `module.Class.foo_bar` is decorated twice according to the order in the list.

Attention

Decorating with `heros.event` leads to a fundamental change in the method since it will be transferred into a `heros.events.LocalEventDescriptor`. This, in turn, implies that no further decorator should be applied after the event. In fact, using any other decorator in combination with the event decorator may lead to unexpected, undocumented behavior.

## Datasource Keys

The `datasource` dictionary supports the following keys:

Key | Type | Description
--- | --- | ---
`async` | bool | If `true`, the device class handles the `observable_data` event by itself. If `false`, the `observable_data` function is polled periodically.
`interval` | number | Polling interval in seconds.
`observables` | dictionary | Dictionary of class attributes that are polled and emitted with the `observable_data` event.

## External Library Integrations

Some drivers from other Python libraries require extra treatment for compatibility with HEROS.

BOSS supports auto wrapping of these drivers to make them compatible for some drivers. The `wrap_target` key gives extra control over this wrapping. If not specified or `auto`, BOSS determines the wrapping automatically from the target class base classes. If `no_wrap`, wrapping is disabled. To force a specific wrapping, set the value to the name of the wrapping lib (for example qcodes).

See hardware-external for supported libraries.

## Multiple HERO Configs

To define multiple HERO configs, use the `rows` key:

    {
        "rows": [
            {
                "_id": "hero_name_1",
                "classname": "module.class",
                "arguments": {},
                "datasource": {}
            },
            {
                "_id": "hero_name_2",
                "classname": "module.class",
                "arguments": {},
                "datasource": {}
            }
        ]
    }

Warning

The `couchdb` API may enclose the HERO config dictionary in a `doc` keyword. This is handled automatically, so do not use `doc` as a top-level key in your configuration.

Tip

You may use additional keys for specific use cases, such as CouchDB views. For more information, see Using Views.