Package json file

Warning

This docmentation is only valid for json version 2 and up. To learn how to upgrade read the json file upgrade documentation

Purpose

The Json file describe the package and the features of the package. There is one common part which is the same for all packages type and some optionnal parts that depends on the package type.

Warning

In json, you must write \n each time you want to create a newline in the data.

The common part

Package type : Plugin External
Is section required for package type : yes yes

The common part is like this :

Example

{
    "json_version": 2,
    "identity": {
        "type": "plugin",
        "id": "onwire",
        "category": "onewire",
        "version": "0.1",
        "domogik_min_version": "0.2.0",
        "documentation": 'http://wiki.domogik.org/plugin_onewire',
        "description": 'Manage 1-wire devices...',
        "author": 'Domogik',
        "author_email": 'xx@xxx.fr',
        "changelog" : "0.1\n-Create plugin",
        "dependencies": [
            {
                "id": "owfs (>=2.8.4)",
                "type": "other"
            }
        ],
     },
    "files": [
        "src/share/domogik/design/plugin/onewire/icon.png",
        "src/share/domogik/plugins/onewire.json",
        ...
    ],
}

Description

  • json_version : version of the json file for this particular element type.

    • identity : element identity.

      • type : the type id for the element:

        • plugin.
        • external.

      • id : package id (name).

      • category : package category (for a plugin, it will be its technology).

      • version : package version.

      • domogik_min_version : minimum Domogik version required by the package.

      • description : package description.

      • author : Name or surname of the developper.

      • author_email : email the developper.

      • documentation : link to the specification page.

      • changelog : changelog. For each version you must indicate the fixes/upgrades.

      • dependencies : table of dependencies needed by the package :

        • type : type of the dependency

          python : a python dependency (distutils2 format). Ex : ‘pyserial (>=2.5)’, ‘foo (>1.0, <1.8)’, ...

          plugin : a Domogik plugin dependency : another plugin must run in order this one could be functionnal.

          other : another dependency (example : owfs for onewire, which need a manual installation).

    • files : list of the files included in the package.

Optionnal parts

You must add the following parts in the json file when developping a package.

Technology

Package type : Plugin External
Is section required for package type : yes yes

Example

"technology": {
    "description": "1-wire",
    "id": "onewire",
    "name": "1-wire"
},

Description

These data will be inserted in database during the package installation.

  • technology : description of the package technology
    • id : technilogy id.
    • name : tehcnology name.
    • description : short description of the technology.

Device types

Package type : Plugin External
Is section required for package type : yes yes

Example

"device_types": {
    "onewire.thermometer" {
        "description": "Thermometer",
        "id": "onewire.thermometer",
        "name": "Thermometer",
        "commands": ["set_level_bin"],
        "sensors": ["level"],
        "xpl_params": [
                {
                        "key": "channel",
                        "description": "The channel number",
                        "type": "integer",
                },
                ...
        ]
    },
    ...
}

Description

These data will be inserted in database during the package installation.

  • device_types : dictionary of device types, indexed on device_type id

    • id : device type id

    • name : device type name

    • description : short description of the device type

    • commands : list of commands supported by this device type

    • sensors : list of sensors supported by this device type

    • xpl_params : list of parameters that are common to ALL xpl messages for this device type
      • key : the xpl key for the message
      • description : short description of this field
      • type : the value type for this field
      • depending on the type the are other posibilitys (like min_value, max_value, ....)

Configuration elements

Package type : Plugin External
Is section required for package type : yes no

These data are read by the manager.

Example

"configuration": [
    {
        "id": "0",
        "interface": "no",
        "key": "startup-plugin",
        "type": "boolean",
        "options": [],
        "default": "False",
        "description": "Automatically start plugin at Domogik startup",
        "optionnal": "no",
    },
    ...
]

Description

  • configuration : list of the configuration parameters of a plugin

    • id : number of the configuration item. The display order will be related to the id.

    • interface : yes or no. If yes, group with all the following keys with interface = yes. This group of keys allow to configure N iterations of these keys.

    • type : the type of the value to set for the key.

      • string : the default type

      • number : a number

      • boolean : True, False

      • enum : a list of options. Example:

        "type" : "enum",
"options": [
    "ipx800v1",
    "ipx800pro",
    "ipx800v2",
    "ipx800v3"
],

    • options : if type = enum, list the available options in this table.

    • default : suggested value.

    • description : parameter short description.

    • optionnal : yes or no : is the parameter optionnal or not ? It is used only for notification in the user interface.

Todo

detail enum

Udev rules

Package type : Plugin External
Is section required for package type : yes no

Example

"udev-rules": [
    {
        "description": "Usb DS9490R adaptator",
        "filename": "onewire.rules",
        "model": "DS9490R",
        "rule": "SUBSYSTEMS==\"usb\", ATTRS{idVendor}==\"04fa\", ATTRS{idProduct}==\"2490\", SYMLINK+=\"onewire\", MODE=\"0666\""
    }
]

Description

  • udev-rules : list of the suggested udev rules. * description : short desciption of the rule. Indicate the related device model here. * filename : suggested filename to use for the rule. * model : related device model. * rule : the udev rule.

External members identification

Package type : Plugin External
Is section required for package type : no yes

Example

"external": {
    "device_id": "rgb",
    "vendor_id": "arduino"
},

Description

  • external : description of the vendor and device id of the external member. This is used to identify a specific external member model. * device_id : device id. * vendor_id : vendor id.

Commands

Package type : Plugin External
Is section required for package type : yes yes

Example

"commands": {
        "set_level_bin": {
                "name": "Switch On or Off",
                "return_confirmation": true,
                "params": [{
                        "key": "level",
                        "value_type": "binary",
                        "values": [0, 255]
                }],
                "xpl_command": "set_level_bin"
        },
        ...
}

Description

  • Commands : this section describes the commands needed by this plugin, its a dictionary indexed by the command reference

    • name : the name of this command

    • return_confirmation : does rinor need to wait for a confirmation

    • params : the needed params to be able to complete this command (typically these are the values set by the widget)

      • key : the name of the parameter

      • value_type : what type of value we can receive

      • values : the possible values, the format depends on the value_type
        • value_type = binary : then values is a list containing the off and on value
        • value_type = range : then values contains a list of min and max value of the range

    • xpl_command : what xpl command is linked to this command (this field is optional)

Sensors

Package type : Plugin External
Is section required for package type : yes yes

Example

"sensors": {
    "level": {
            "name": "level",
            "unit": "%",
            "value_type": "range",
            "values": [0, 100]
    },
    ...
},

Description

  • Sensors : this section describes the sensors supported by this plugin, its a dictionary indexed by the command reference

    • name : the name of the sensor

    • unit : the unit of this value, needed for ui display

    • value_type: what type of value we can receive

    • values : the possible values, the format depends on the value_type
      • value_type = binary : then values is a list containing the off and on value
      • value_type = range : then values contains a list of min and max value of the range

Xpl_commands

Package type : Plugin External
Is section required for package type : yes yes

Example

"xpl_commands": {
     "set_level_bin": {
        "name": "blah",
        "schema": "lighting.basic",
        "xplstat_name": "get_level",
        "parameters": {
                "static": [
                    {
                        "key": "stat",
                        "value": "stat"
                    }
                ],
                "device": [
                    {
                        "key": "dummy",
                        "description": "a dummy param",
                        "type": "string"
                    }
                ]
            }
     },
     ...
},

Description

  • xpl_command : this section describes the xpl_command to sent when a command is triggered

    • name : the name of the command

    • schema : the xpl schema to use

    • xplstat_name : the xplstat that will be expected as a confirmation

    • parameters : the key/value pairs for the xpl message
      • static : values that are static, these key/value pairs are always there and not changeable
        • key : xpl key
        • value : xpl value
      • device : parameter that can be changed on a per device basis, will be displayed in the create device interface
        • key : xpl key
        • description : the description that will be displayed
        • type : the value type

Xpl_stats

TODO

How to insert the data in database

This action is only for developpers!

If you want to manually insert the data of the json in the database, launch this command :

cd src/tools/packages
./insert_data.py ../../share/domogik/plugins/<your plugin name>.json
« previous | up | next »