Package json file¶
Warning
This documentation 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 optional 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 : |
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 developer.
author_email : email the developer.
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 functional.
other : another dependency (example : owfs for onewire, which need a manual installation).
files : list of the files included in the package.
Optional parts¶
You must add the following parts in the json file when developing a package.
Technology¶
Package type : | Plugin | External |
---|---|---|
Is section required for package type : |
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 : |
Example¶
"device_types": {
"onewire.thermometer" {
"description": "Thermometer",
"id": "onewire.thermometer",
"name": "Thermometer",
"commands": ["set_level_bin"],
"sensors": ["level"],
"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
- 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 possibilities (like min_value, max_value, ....)
Configuration elements¶
Package type : | Plugin | External |
---|---|---|
Is section required for package type : |
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",
"optional": "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.
optional : yes or no : is the parameter optional 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 : |
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 description 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 : |
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 : |
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 : |
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 : |
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 developers!
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