================= Package json file ================= .. warning :: This docmentation is only valid for json version 2 and up. To learn how to upgrade read the json file :doc:`upgrade ` documentation .. |yes| image:: yes.png .. |no| image:: no.png 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/.json