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.

Special Arguments¶

{
    "_id": "hero_name_1",
    "classname": "module.class",
    "arguments": {
        "loop": "@_boss_loop",
        "pool": "@_boss_pool"
    }
}

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.

Process Pool¶

Upon start, BOSS creates an concurrent.futures.ProcessPoolExecutor, this pool can be passed to the target class via @_boss_pool. The number of workers can be controlled via the parameter --max-workers when starting BOSS.

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.
`observable`	list	List of class attributes that are polled and emitted with the `observable_data` event.

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.