diff --git a/README.md b/README.md
index eaa2e5e..95c8be1 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
-**Specification reversion:** ${/var/document-version} - ${/var/creation-time}
+**Specification version:** ${/var/document-version} - ${/var/creation-time}
[HISTORY](./vscp_specification_history.md)
Specification is [here](https://docs.vscp.org)
@@ -14,7 +14,7 @@ Apart from going through this document You can read all about and download VSCP
**VSCP is free.** Free to use. Free to change. Free to do whatever you want to do with it. VSCP is not owned by anyone. VSCP will stay free and gratis forever.
-Author 2000-2020 Åke Hedman, [Grodans Paradis AB](https://www.grodansparadis.com), [akhe@grodansparadis.com](akhe@grodansparadis.com)
+Author 2000-2022 Åke Hedman, [Grodans Paradis AB](https://www.grodansparadis.com), [akhe@grodansparadis.com](akhe@grodansparadis.com)
This document is licensed under [Creative Commons BY 4.0](https://creativecommons.org/licenses/by/4.0/) and can be freely copied, redistributed, remixed, transformed, built upon as long as you give credits to the author.
diff --git a/variables.xml b/variables.xml
index e3291b4..1c187bf 100644
--- a/variables.xml
+++ b/variables.xml
@@ -1,4 +1,4 @@
- 2021-10-05 16:46
- 1.12.5
+ 2022-01-13 09:24
+ 1.13.0
diff --git a/vscp_module_description_file.md b/vscp_module_description_file.md
index 6e296e3..e1bc6c4 100644
--- a/vscp_module_description_file.md
+++ b/vscp_module_description_file.md
@@ -1,30 +1,37 @@
# Module Description File
-The VSCP registers 0xE0-0xFF specifies the Module Description File URL (without “http://”` or `“https://” which is implied). The file is in XML or JSON format and defines a modules functionality, registers and events. The intended use is for application software to be able to get information about a node and its functionality in an automated way.
+The Module Description File (MDF) is a file that describes a general hardware module. The format of the file can be used to describe any logical or physical device. After parsing the MDF a higher level device (a machine) or user (a human) know how to configure and handle the described module.
- * A XML coded MDF file shall start with a '<'. It is allowed to have white space before this character.
- * A JSON coded MDF file shall start with a '{'. It is allowed to have white space before this character.
+All VSCP modules have an area in memory that is common to all devices that contains the URL for the MDF. This area can be read and then the MDF can be downloaded and parsed.
-On Level II devices this information can be available in the configuration data and be locally stored on the node. If language tags are missing for a name or a description or in an other place where they are valid English should be assumed.
+The file should be UTF-8 encoded and contain either **XML** or **JSON** data.
-**Coding:** UTF-8
+**numbers** All numbers can be set as decimal(no prefix), hexadecimal(prefix with 0x), octal(prefix with 0o) or binary(prefix with 0b).
-## Real life file examples
-### Kelvin NTC10K
-
-The Kelvin NTC10K is one of [Grodans Paradis AB's](https://www.grodansparadis.com/) modules and it has it's product page [here](https://www.grodansparadis.com/kelvinntc10k/kelvin_ntc10ka.html). The MDF file for this modules is [here](https://www.eurosource.se/ntc10KA_1.xml).
+## The content of a MDF file
-### Paris relay module
+The MDF file have the following general structure:
-The Paris module is another module from Grodans Paradis AB and it is documented [here](https://www.grodansparadis.com/paris/paris.html). The MDF file for this modules is [here](https://www.eurosource.se/paris_010.xml).
+ - **General module information** such as model, version etc.
+ - **Manufacturer**: Info about the maker of the module such as name, address, phone number, etc.
+ - **Files**: A list oif files related to the module. This can be firmare, pictures, videos, manuals etc.
+ - **bootloader information**: Info on how to load firmware to the module.
+ - **registers**: A list of byte wide registers the module have.
+ - **remote variables**: A list of remote variables the module have. Remote variables was called *abstractions* in previous versions of the specification.
+ - **events**: A list of events (and there format) the module can generate/receive.
+ - **decision matrix**: Describes the decision matrix for the module if it have one.
+ - **setup**: Is macros to setup and configure and control a module using wizard like interfacec.
## XML Format Specification
+### Format notes
-##### Notes
+#### Register definitions
+Register definitions must be available for all nodes (if the module have registers defined).
-Register definitions must be available for all nodes (if it has registers defined). A register which does not have a an abstraction defined will be handled with a default abstraction constructed from its offset as
+#### Automatic remote variables
+A register which does not have a a remote variable defined to describe it in a high level way will have a default remote variable constructed from its offset as
register''offset''
@@ -32,1472 +39,3222 @@ for example
register1
-The type will always be “uint8_t” in this case
+The type for the remote variable in this case will always be “uint8_t”
+
+#### Newlines
+“\n” can be used to define a new line in descriptive text. It will be translated in an appropriate way by the renderer.
-“\n” can be used for a new line in text.
+## File overall structure
-If you want to insert HTML as content use a construct like this
```xml
-
-
-
-
-
- Your HTML's body
-
-
-]]>
+
+
+
+
+ "The module is described here"
+
+
+
```
-this is especially useful for info, description and help items.
+### Redirect
+The redirect can be used to tell the parser to download the MDF from a different URL.
-##### Format
+### Module
+In the **module**-block the module is described. Currently only one module can be defined in a mdf file. This may change in the future.
+## Module information
-**XML**
+Every module should have an initial block that describes the module. This block is called the **General module information**. The block looks like this
```xml
-
-
-
-
-
-
-
-
-
-
- aaaaaaaa
+
+ aaaaaaaa
bbbbb
cccccc
- yyyyyyyyyyyyyyyyyyyyyyyyyyyy
-
-
- http://www.somewhere.com
+ yyyyyyyyyyyyyyyyyyyyyyyyyyyy
+ Main driver info help (web) page url
-
-
-
- tttttttttttttttttttt
-
-
- ttttttttttttt
- llllllllll
- London
- HH1234
-
-
-
- ttttt
-
-
-
-
- 123456789
- Main Reception
-
-
-
-
- 1234567879
- Main Fax Number
-
-
-
-
- someone@somwhere.com
- lang="en">Main email address
-
-
-
-
- www.somewhere.com
- Main web address
-
-
-
-
-
- Main email address
- Where the driver can be fetched from
- (one or many)``
-
-
-
-
- Description of picture
-
-
-
-
- Firmware description
-
-
-
-
- ``Firmware description``
-
-
-
-
-
-
- tttt
- yyy
- tttt
- rw
-
-
-
-
- tttt
- yyy
- tttt
- rw
-
-
-
-
-
- tttt
- yyy
- tttt
- rw
-
-
-
- tttt
- yyy
- tttt
- r
-
- -
- item0
- item0_description
-
- -
- item1
- item1_description
-
- -
- item2
- item2_description
-
- -
- item3
- item3_description
-
- -
- "item4
- item4_description
-
- -
- item5
- item5_description
-
- -
- item6
- item6_description
-
- -
- item7
- item7_description
-
- -
- item8
- item8_description
-
-
-
-
-
-
- Indexed array of values
-
- This is an array of six 16-bit integers. Register 116 is the index
- inte the array which is at 117. So setting register 116 to 0 will
- put the MSB of the first integer into register 117 ans so on.
-
- rw
-
-
-
-
-
-
-
-
-
+ 8
+
+```
+#### name
+Name is the name of the module. A unique describing name is recommended. This name will be translated to lower case and is used as the name of the module when referring to it in software.
+
+**note** In previous version the name of the module was language specific just as descriptions and info url's. This is no longer the case. If
+
+```xml
+
+
+ aaaaaaaa
+ bbbbbbbb
+```
+
+the last parsed name will be used.
+
+#### model
+This is the model of the module. Format is defined by the designer.
+
+#### version
+This is the version of the module. Format is defined by the designer.
+
+#### description
+The description is a short description of the module. It is recommended to use a language specific description. If no language attribute is given "en" for English will be used. The language code should be a valid two letter (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+Descriptions can be multiline and can use "\n" to define a new line.
+
+As an example
+
+```xml
+ xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ yyyyyyyyyyyyyyyyyyyyyyyyyyyy
+ zzzzzzzzzzzzzzzzzzzzzzzzzzzz
+```
+
+will create an English, Lithuanian, and a Spanish description. Software that handle languages can then switch between languages fast and efficiently.
+
+#### infourl
+The infourl is an url pointing to a full description of the module in the language given by the **lang** attribute. It is recommended to use a language specific infourl. If no language attribute is given "en" for English will be used. The language code should be a valid two letter (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+As an example
+
+```xml
+ https://www.somewhere.com
+ https://www.somewhere.lt
+ https://www.somewhere.es
+```
+
+points to web pages that have info in three different languages.
+
+#### buffersize
+For Level II nodes the buffer size specify the max VSCP data a node can receive. This makes it possible to have nodes, that due to low internal resources, that can receive events, but not all events, just those under a specified maximum size. The default is eight bytes which is the data size for a level I node. Set to <= 512 for a level II nodes.
+
+### manufacturer:id=manudacturer_xml
+The manufacturer block describes the manufacturer of the module.
+
+#### name
+Name is the name of the company that manufactured the module.
+
+**note** In previous version the name of the module was language specific just as descriptions and info url's. This is no longer the case.
+
+#### Address
+The address block looks like this
+
+```xml
+
+ Some street in Camden, London
+ Camden
+ London
+ Postal code
+ xxxxxx<
+ London
+ Country
+
+```
+
+and specify the address to the manufacturer of the module. Use the tags that are appropriate for your project.
+
+**note** In previous version the address of the module was language specific just as descriptions and info url's. This is no longer the case. Only one address can be defined.
+
+
+#### Telephone
+This is a phone number of the manufacturer. As many phone numbers as one like can be defined. The format is
+
+```xml
+
+ +46 8 40011835
+ office exchange
+ https://www.somewhere.com
+
+```
+The infourl is optional.
+
+#### Fax
+This is a telefax number of the manufacturer. As many fax numbers as one like can be defined. The format is
+
+```xml
+
+ +46 8 40011837
+ office fax
+ https://www.somewhere.com
+
+```
+The infourl is optional.
+#### Email
+This is an email address of the manufacturer. As many email addresses as one like can be defined. The format is
+
+```xml
+
+ info@vscp.org
+ office exchange
+ https://www.somewhere.com
+
+```
+The infourl is optional.
+#### Web
+This is a web address of the manufacturer. As many web addresses as one like can be defined. The format is
+
+```xml
+
+ https://www.somewhere.com
+ office exchange
+ https://www.somewhere.com
+
+```
+The infourl is optional.
+
+### Files:id=files_xml
+
+```xml
+
+ ...
+ ...
+
+ ...
+ ...
+ ...
+
+```
+
+This block contains info about files that are related to the module. _picture_, _videos_, _firmware_, _driver_ and _manual_ are current defined types of files. _setup_ is reserved for future use.
+
+#### firmware:id=firmware_xml
+
+In the firmware block you can specify links to firmware file that is used by the module and describe them. The format is
+
+```xml
+
+
+ https://www.somewhere.com/firmware.zip
+ Firmware description
+ https://www.somewhere.com
+
+
+```
+
+Any number of language specific _descriptions_ and/or _infourl_'s can be set for each firmware item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **target** | Set the target for the file here. The target is typically processor and architecture specific. Examples are "PIC18F2558", "PIC18F26K50" and so on. It is up to the maker of the module to define unique values. |
+| **targetcode** | Set the target code for the file here. The target code is typically a 16-bit unsigned value that is stored inte the nodes flash. If not null a firmware file that should be written to a node should have the same target code value as the the device registers have written to them. |
+| **url** | The url from which the firmware file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the firmware file. |
+| **format** | The format of the firmware file. "intelhex8" and "intelhex16" is current valid values. |
+| **size** | The size of the firmware file in bytes. Zero if not set.|
+| **date** | Release date for the firmware. |
+| **version_major** | Major version number for firmware. |
+| **version_minor** | Minor version number for firmware. |
+| **version_subminor** | Sub minor version number for firmware. |
+| **md5** | MD5 checksum for the firmware file as hexadecimal string. Empty if not used. |
+
+#### Example
+
+```xml
+
+
+ Firmware (PIC18F2580) for the Vilnius A/D module for use with the VSCP Bootloader wizard.
+
+
+ Firmware (PIC18F26K80) for the Vilnius A/D module for use with the VSCP Bootloader wizard.
+
+
+ Firmware for the Vilnius A/D module for use with the VSCP Bootloader wizard.
+
+
+ Firmware for the Vilnius A/D module for use with the VSCP Bootloader wizard.
+
+
+```
+
+#### picture:id=picture_xml
+
+In the picture block you can specify a link to an image file that in some way is related the module and describe it. The format is
+
+```xml
+
+
+ https://www.somewhere.com/picture.jpg
+ Description of picture
+ https://www.somewhere.com
+
+
+```
+
+Any number of anguage specific descriptions and/or infourl's can be set for each picture item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the picture file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the picture file. |
+| **format** | The format of the picture file. "png", "jpeg" and "jpg" is current valid values. |
+
+#### video:id=video_xml
+
+In the video block you can specify a link to a video file that in some way is related the module and describe it. The format is
+
+```xml
+
+
+
+```
+
+Any number of language specific descriptions and/or infourl's can be set for each video item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the video file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the video file. |
+| **format** | The format of the video file. "mp4", "mov" and "avi" is current valid values. |
+
+#### manual:id=manual_xml
+
+In the manual block you can specify a link to a manual file that in some way is related to the module and describe it. The format is
+
+```xml
+
+
+ https://www.somewhere.com/driver.zip
+ Description of driver
+ https://www.somewhere.com
+
+
+```
+
+Any number of language specific descriptions and/or infourl's can be set for each manual item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the video file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the video file. |
+| **format** | The format of the video file. "txt", "md" (markdown), "html" and "pdf" is current valid values. |
+| **lang** | The language of the manual. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6]. |
+
+#### driver:id=driver_xml
+
+In the driver block you can specify a link to a driver for a specific version of an operation system file that in some way is related the module and describe it. Typically this is a device driver or a VSCP daemon driver or similar. zip and gz packed files are allowed. The format is
+
+```xml
+
+
+ https://www.somewhere.com/driver.zip
+ Description of driver
+ https://www.somewhere.com
+
+
+```
+
+Any number of language specific descriptions and/or infourl's can be set for each driver item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the video file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the video file. |
+| **os** | The operating system. Examples are "Debian Linux", "Microsoft Windows" etc |
+| **osver** | The version of the operating system. Examples are "10", "8.1" etc |
+| **version_major** | Major version number for driver. |
+| **version_minor** | Minor version number for driver. |
+| **version_subminor** | Sub minor version number for driver. |
+| **md5** | MD5 checksum for the driver file as hexadecimal string. Empty if not used. |
+#### setup:id=setup_xml
+
+In the setup block you can specify a link to a setup file that contain a VSCP setup script that do a specific setup of the device. The format is
+
+```xml
+
+
+ https://www.somewhere.com/setup.js
+ Description of setup script
+ https://www.somewhere.com
+
+
+```
+
+Any number of language specific descriptions and/or infourl's can be set for each setup item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the video file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the video file. |
+| **format** | The format of the setup file. "vscpjs" for VSCP javascript setup is the only current valid value. |
+
+### Bootloader block:id=bootloader_xml
+
+```xml
+
+ Algorithm code
+ Size of each block
+ Number of blocks
+
+```
+
+The bootloader block specify the bootloader algorithm that should be used to download firmware code to the module. The code for a specific module is defined in standard register *151/0x97*. The possible codes is here [CLASS1.PROTOCOL, Type=12](./class1.protocol.md#id=type12).
+
+Firmware listed in the *Module Description File* file block have a [targetcode](#firmware) as an attribute. This code specify the hardware for a version of the a module the firmware is intended for. Typically the code is different for modules of the same type which have different versions of micro processor, memory, peripherals etc and therefore need different versions of the firmware. A bootloader should read this register and verify the targetcode with the content of the target code registers before loading firmware as loading wrong firmware version can brick a module.
+
+### Registers:id=registers_xml
+
+```xml
+ ...
+ ...
+ ...
+ ...
+ ...
+ ...
+
+```
-
-
- alsoaname_msb
- MSB of alsoaname
- tttt
- rw
-
+All defined registers of a module is defined in the registers block. The format is
-
- tttt
- alsoaname_lsb
- LSB of alsoaname
- rw
+```xml
+
+ Description of register
+ Link to url that have language specific information about the register
+```
+An alternative (but deprecated) form is
-
-
- tttt
- abcdefghih
- The string adescriptivename
- rw
+```xml
+
+ symbolic name for register Should be unique.
+ Description of register
+ Link to url that have language specific information about the register
+ rw
+```
-
-
- tttt
- tttt
- yyy
- rw
-
- tttt
- yyy
- tttt
-
-
- tttt
- yyy
- tttt
-
-
- tttt
- yyy
- tttt
-
-
- tttt
- yyy
- tttt
-
-
-
- tttt
- yyy
- tttt
-
-
+#### Attributes
-
-
-
- tttt
- yyy
- tttt
- rw
-
- -
- undefined
- yyy
- tttt
-
- -
- Normal
- yyy
- tttt
-
- -
- Error
- yyy
- tttt
-
- -
- Disabled
- yyy
- tttt
-
- -
- "Test
- yyy
- tttt
-
- -
- Disposed
- yyy
- tttt
-
- -
- PowerSaving
- yyy
- tttt
-
- -
- Stopped
- yyy
- tttt
-
- -
- Paused
- yyy
- tttt
-
-
-
-
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. Should be unique.|
+| **page** | The page on whish the register is located. |
+| **offset** | The zero based offset on the page where the register is defined. Level I: 0-127. Level II: 0-0xFFFFFFFE |
+| **type** | Specify the register type. A register is by default defined as 'std' which is a standard register. But 'block' can be used for a consecutive number of registers. Another form is 'dmatrix1' which is the standard level I decision matrix. For the non standard form span tells the number of registers used in the block and the full decision matrix |
+| **span** | Number of bytes for the register. This defaults to one as expected. But for the 'block' and the 'dmatrix1' types it tell the number of consecutive bytes used. Both 'block' and 'dmatrix1' types of registers will get names specified from the name attribute with a incrementing number appended for each register (name1, name2, name3...) |
+| **width** | Can be used to limit the registers bit width from 8-1. Default is eight. |
+| **size** | (Deprecated. Do not use) Size in bytes for register. Default = 1 |
+| **min** | Minimum value for register. Default = 0 |
+| **max** | Maximum value for register. Default = 255 |
+| **access** | Specify the access rights for the register. Can be 'r' (read), 'w' (write) or 'rw' (read/write. Default is 'rw' |
+| **default** | VSCP Works specific: Default value in string form. Default is 'UNDEF' Used by VSCP Works to restore default value to a register. |
+| **fgcolor** | VSCP Works specific: foreground color. Used as foreground color by VSCP Works when rendering this register row. |
+| **bgcolor** | VSCP Works specific: background color. Used as background color by VSCP Works rendering this register row. |
-
-
- tttt
- yyy
- tttt
- r
-
- -
- undefined
- yyy
- tttt
-
- -
- Normal
- yyy
- tttt
-
- -
- Error
- yyy
- tttt
-
- -
- Disabled
- yyy
- tttt
-
- -
- "Test
- yyy
- tttt
-
- -
- Disposed
- yyy
- tttt
-
- -
- PowerSaving
- yyy
- tttt
-
- -
- Stopped
- yyy
- tttt
-
- -
- Paused
- yyy
- tttt
-
-
+Any number of language specific descriptions and/or infourl's can be set for each register item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+The 'name' tag can be set also in a none attribute way. This is true for the 'access' tag as well. This usage is deprecated.
+
+#### Example 1
+A typical register definition:
+
+```xml
+
+
+ Zone this module belongs to
+
+
+ Subzone this module belongs to
+
+
+```
+
+#### Example 2
+A register with max min values and which just use four bits and language dependent descriptions.
+
+```xml
+
+
+ Limited register
+ Begränsat register
+ Ribotas registras
+ 有限的寄存器
+
+
+```
+
+#### Example 3
+A register of block type
+
+```xml
+
+
+
+ This is register of block type.\n
+ Description is\n
+ multiline\n
+
+
+
+```
+
+When rendered in VSCP Works or other programs this be rendered as:
+
+```
+control_register0
+control_register1
+control_register2
+control_register3
+control_register4
+control_register5
+control_register6
+control_register7
+```
+
+#### Register value lists:id=register_value_lists_xml
+
+Register definitions can have values lists. A value list is a list of values that can be used for a register.
+
+```xml
+
+ English description of the register.
+ Svensk beskrivning av registret.
+
+ -
+ Description item 0
+ InfoURL item 0
+
+ -
+ Description item 1
+ InfoURL item 1
+
+ -
+ Description item 2
+ InfoURL item 2
+
+
+```
+
+The valuelist specify a number of values (*items*) that can be used for a register. These values will be rendered as a drop down list in VSCP Works from which the user can select a value. Each item have a name and a value. The name is used to identify the item in the drop down list. The value is the actual value that will be used when the register is written. Language dependent descriptions and/or infourl's can be set for each item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
-
-
- Trust
- yyy
- tttt
+##### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the value item. |
+| **value** | Value for the item. |
+
+Any number of language specific descriptions and/or infourl's can be set for each value item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+#### Register bit fields:id=register_bit_fields_xml
+
+You can define a register as a bit field. A bit field is a register that is split into a number of bits. The bits are defined in a bit field list. There can be a maximum of eight bits defined for a register.
+
+```xml
+
+ Register bits
+
+ Reserved.
+ Reserverad.
+ en url0
+ se url0
+
+ -
+ Bit value description item 0
+ Bit url0
+
+ -
+ Bit value description item 1
+ Bit url1
+
+ -
+ Bit value description item 2
+ Bit url2
+
+ -
+ Bit value description item 3
+ Bit värde beskrivning item 3
+ Bit url3
+ Bit url3 se
+
+
+
+
+ Reserved1.
+
+
+ Reserved2.
+
+
+```
-
+As seen above [valuelists](#register_value_lists) can be used for bit fields as well. See docs above.
+
+##### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the bit field. |
+| **pos** | Bit position in the byte (0-7). |
+| **width** | The number of bits in the bit field. If set to 2 with pos=0 then bit 0 and bit 1 will be used for the bit field. |
+| **default** | Default value for the bit field. 'true'/'false' or a numerical value. |
+| **min** | Minimum value for register. Default = 0 |
+| **max** | Maximum value for register. Default = 255 |
+| **access** | Specify the access rights for the register. Can be 'r' (read), 'w' (write) or 'rw' (read/write. Default is 'rw' |
+
+Any number of language specific descriptions and/or infourl's can be set for each register item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+### Remote Variables (Abstractions):id=remote_variables_xml
+
+```xml
+
+
+ Remote variable description.
+ Beskrivning av variable.
+ Remote var url en
+ Variabel url se
+
+
+```
+
+or alternatively
+
+```xml
+
+
+ ch0_value
+ A/D value for channel 0.
+ A/D värde för kanal 0.
+ Remote var url3
+ Remote var url3 se
+ r
+
+
+```
+
+Remote variables or *abstractions*, as they was named in previous versions of the VSCP specification, is a higher level view of register space. Here we look at the storage using well known variable typers such as stings, integers and floats. This makes it easier to use the register values in a configuration script etc.
+
+All remote variables are mapped into register space and are stored there big endian, that is with the high byte in the first byte. An 16-bit integer will accordingly be stored with the MSB byte in the first register and the LSB in the second byte and so on.
+
+There is no need to define remote variables for bytes as they are already defined in the register space. Automatic remote variables will be created for registers that do not have a remote variable defined. These will be named as follows:
+
+
+_rv__
+
+So for example if you have a register named "Reg1" then the remote variable will be named "_rv_reg1_".
+
+Needless to say names with this pattern are reserved.
+#### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the remote variable. |
+| **type** | A type for the remote variable. Remote variable types are [here](./vscp_register_abstraction_model.md#remote-variables). |
+| **page** | The page where the remote variable is stored. |
+| **offset** | The offset off the page where the MSB of the remote variable is stored. |
+| **bitpos** | The bit of a register used for a boolean. If not set and the type is boolean bit 0 will be used. No meaning for other types. |
+| **size** | The size of a remote variable that is of type string. The size is the max size of the buffer. |
+| **access** | Specify the access rights for the remote variable. Can be 'r' (read), 'w' (write) or 'rw' (read/write. Default is 'rw' |
+
+In the same way as registers remote variables can also have valuelists and bit fields. See docs above.
+
+#### Example with valuelist
-
+```xml
+
+ Value test 1
+
+ -
+ Description item 0
+ InfoURL item 0
+
+ -
+ Description item 1
+ InfoURL item 1
+
+ -
+ Description item 2
+ InfoURL item 2
+
+ -
+ Description item 3
+ InfoURL item 3
+
+
+
+```
+#### Example with bit fields
+
+```xml
+
+ Bit test 1.
+
+ Reserved.
+ Reserverad.
+ en url0
+ se url0
+
+ -
+ Bit value description item 0
+ Bit url0
+
+ -
+ Bit value description item 1
+ Bit url1
+
+ -
+ Bit value description item 2
+ Bit url2
+
+ -
+ Bit value description item 3
+ Bit värde beskrivning item 3
+ Bit url3
+ Bit url3 se
+
+
+
+
+ Reserved1.
+
+
+ Reserved2
+ Reserved2.
+
+
+ Reserved3
+ Reserved3.
+
+
+ Reserved4
+ Reserved4.
+
+
+ Reserved5
+ Reserved5.
+
+
+ Reserved6
+ Reserved6.
+
+
+ Reserved7
+ Reserved7.
+
+
+```
+
+### Alarms:id=alarm
+```xml
+
+
+ Reserved 7.
+ https://www.somewhere.com/info7.html
+
+
+ Reserved 6.
+ https://www.somewhere.com/info6.html
+
+
+ Reserved 5.
+ https://www.somewhere.com/info5.html
+
+
+ Reserved 4.
+ https://www.somewhere.com/info4.html
+
+
+ Reserved 3.
+ https://www.somewhere.com/info3.html
+
+
+ Reserved 2.
+ https://www.somewhere.com/info2.html
+
+
+ High alarm. The value of one of the A/D channels has gone above the high alarm level.
+ https://www.somewhere.com/info1.html
+
+
+ Low alarm. The value of one of the A/D channels has gone under the low alarm level.
+ https://www.somewhere.com/info0.html
+
+
+```
+
+The alarm block specify the meaning of the alarm bits in the standard alarm register [128/0x80](./vscp_register_abstraction_model.md#register_abstraction_model). In the block there is a bit filed of max eight bit definitions each describing the alarm bits of the register. You just need to specify the bits that is used.
+
+#### Attributes
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the alarm bit. |
+
+Any number of language specific descriptions and/or infourl's can be set for each register item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+### Decision Matrix:id=dm_xml
+
+```xml
+
+
+ English description of the action 0.
+ Svensk beskrivning av action 0.
+ url1_en
+ url1_se
+
+ Description of parameter for action 0.
+ https://www.somewhere.com/info0.html
+
+
+
+ English description of the action 1.
+ Svensk beskrivning av action 1.
+ url1_en
+ url1_se
+
+ Description of parameter for action 1.
+ https://www.somewhere.com/info0.html
+
+
+
+```
+or alternatively
+
+```xml
- tttt
-
-
- 1
-
-
-
-
-
-
- 10
-
-
- 8
-
-
-
-
-
- tttt
-
-
-
-
- tttt
-
-
- tttt
- yyy
- tttt
-
- tttt
- yyy
- tttt
-
-
-
-
-
+ 1
+
+ 4
+
+
+ Counter
+ Counter 0-3 to start.
+ https://www.somewhere.com/info0.html
+
+
+
+```
+
+If the module have a [decision matrix](./vscp_decision_matrix.md) it can be defined here. You specify where in the register space the decision matrix is located and the numer of rows for the matrix. The decision matrix holds an array of actions. Each row in the matrix is a row in the register space. The actions are defined in the action block.
+
+For a level I decision matrix there is one and only one parameter for each action. For Level II decision matrixes however there can be several (defined by the attribute *rowsize*). In both cases the parameter(s) is described in the param block.
+
+#### Attributes dmatrix
+
+| Name | Description |
+| :---- | :----------- |
+| **level** | Decision matrix level 1/2. Default=1. |
+| **start-page** | The page where the decision matrix is stored in register space. |
+| **start-offset** | The offset of the register page where the decision matrix is stored. |
+| **rowcnt** | Number of decision matrix rows. |
+| **rowsize** | Number of decision matrix bytes on each row. For a level I decision matrix this is always eight. Default=8. |
+
+#### Attributes action
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | Name for the action. |
+| **code** | The numerical code for the action (0-255). |
+
+#### Attributes action parameter
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | Name for the action parameter. |
+| **offset** | Parameter field offset. Always zero for level I decision matrix as it always have only one parameter. Default = 0 |
+| **min** | Minimum value for the parameter. Default = 0. |
+| **max** | Maximum value for the parameter. Default = 255. |
+
+Any number of language specific descriptions and/or infourl's can be set for each register item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Example
+```xml
+
+
+ No operation.
+ Ingen operation.
+ url0_en
+ url0_se
+
+
+ Set the enable bit and thereby start the counter given by the argument which should be a value of 0-3 representing counter0 - counter3.
+ Sätt aktiveringsbiten och starta den räknare som anges av argumentet vilket skall vara ett värde 0-3 för counter0 - counter3.
+ url1_en
+ url1_se
+
+ Counter 0-3 to start.
+
+ -
+ Counter 0.
+ Räknare 0.
+ url0_en
+ url0_se
+
+ -
+ Counter 1.
+ Räknare 1.
+ cnt_url1_en
+ cnt_url1_se
+
+ -
+ Counter 2.
+ Räknare 2.
+ cnt_url2_en
+ cnt_url2_se
+
+ -
+ Counter 3.
+ Räknare 3.
+ cnt_url3_en
+ cnt_url3_se
+
+
+
+
+
+ Clear the enable bit and thereby stop the counter given by the argument which should be a value of 0-3 representing counter0 - counter3.
+
+ Counter 0-3 to start.
+
+ -
+ Counter 0
+
+ -
+ Counter 1
+
+ -
+ Counter 2
+
+ -
+ Counter 3
+
+
+
+
+
+ Clear the the value for the counter given by the argument which should be a value of 0-3 representing counter0 - counter3.
+
+ Counter 0-3 to start.
+
+ -
+ Counter 0
+
+ -
+ Counter 1
+
+ -
+ Counter 2
+
+ -
+ Counter 3
+
+
+
+
+
+ Reload counter
+ Load the reload value to the counter given by the argument which should be a value of 0-3 representing counter0 - counter3.
+
+ Counter 0-3 to start.
+
+ -
+ Counter 0
+
+ -
+ Counter 1
+
+ -
+ Counter 2
+
+ -
+ Counter 3
+
+
+
+
+
+ Add or subtract one from a counter depening on its count direction setting.
+
+ Counter 0-3 to start.
+
+ -
+ Counter 0
+
+ -
+ Counter 1
+
+
+
+
+
+ Action With Bits
+
+ Param With Bits
+
+ Test bit description low bits.
+ Test bit beskrivning low bits.
+ test infourl low bits
+ test infourl låga bitar
+
+
+ Test bit description high bits.
+ Test bit beskrivning high bits.
+ test infourl high bits
+ test infourl höga bitar
+
+
+ Test bit description value bits.
+ Test bit beskrivning value bits.
+ test infourl value bits
+ test infourl value bitar
+
+ Value list in bit array.
+ -
+ Value1 description.
+ Beskrivning av värde.
+ Value1 infourl.
+ Värde 1 infourl.
+
+ -
+ Value2 description.
+ Value2 infourl.
+
+
+
+
+
+```
+
+### Events:id=events_xml
+
+```xml
+
+
+ Info about event in english
+
+ English description of data byte 0
+ https://www.somewhere.com/info0.html
+
+
+ English description of data byte 1
+ https://www.somewhere.com/info0.html
+
+
+ English description of data byte 2
+ https://www.somewhere.com/info0.html
+
+
+
+```
+
+In the *event* block events that the module can receive and handle is described but maybe even more importantly events that the module send out itself can be 34 described. A *data* block is defined for each data byte of the event describing it.
+
+For data blocks bit fields and value lists can be used. See description above for more information.
+
+#### Attributes event
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | Name for the event. |
+| **class** | Event class. Mandatory. Can be set to '-' whish means all classes. |
+| **type** | Event type. Mandatory. Can be set to '-' whish means all types. |
+| **priority** | Priority for the event. Default=3. |
+| **dir** | Direction of event. "in" is incoming event. "out" is outgoing event. Default="out" |
+
+#### Attributes event data
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | Name for the event data byte. |
+| **offset** | Data byte offset. |
+
+Event data can use value lists and bit fields. See description above for more information.
+
+#### Example
+
+```xml
+
+
+ Count data steam event sent on regular intervals if activated. Coding: Integer. Unit: none.
+
+ Will contain 0b01100xxx where xxx is the counter (0-3/4-7) and where 0-3 is the counter 32-bit value and 4-7 is the 32-bits of the 64-bit counter value stored internally.
+
+
+ Byte 0 (MSB) of 32-bit counter value.
+
+
+ Byte 1 of 32-bit counter value.
+
+
+ Byte 2 of 32-bit counter value.
+
+
+ Byte 3 (LSB) of 32-bit counter value.
+
+
+
+ If an alarm is armed this event is sent when it occurs and the corresponding alarm bit is set in the alarm register.
+
+ Index
+ Counter alarm has occured on (0-3).
+
+
+ Zone
+ Is set to the zone for the module.
+
+
+ Sub zone
+ Sub zone for channel or sub zone for module if channel sub zone is zero.
+
+
+
+ Frequency measurement event sent on regular intervals if activated. Coding: 32-bit integer. Unit: Hertz.
+
+ Datacoding: 0b01100xxx where xxx is the counter (0-3)
+
+
+ Frequency value as 32-bit floating point value with MSB in first byte.
+
+
+ Frequency value as 32-bit floating point value with MSB in first byte.
+
+
+ Frequency value as 32-bit floating point value with MSB in first byte.
+
+
+ Frequency value as 32-bit floating point value with MSB in first byte.
+
+
+
+ Measurement values of all kinds can be sent as a result of linearization. For example can an input counting S0 pulses be translated to KWh and watt
+
+ Datacoding: Always as a 32-bit floating point value. 0b101yyxxx where yy is the unit and xxx is the counter (0-3)
+
+
+ MSB of the 32-bit floating point value that has been calculated from the linearization equation.
+
+
+ 32-bit floating point value that has been calculated from the linearization equation.
+
+
+ 32-bit floating point value that has been calculated from the linearization equation.
+
+
+ LSB of the 32-bit floating point value that has been calculated from the linearization equation.
+
+
+
+```
+
+## Real life MDF XML formatted file examples
+
+### Kelvin NTC10K
+
+The Kelvin NTC10K is one of [Grodans Paradis AB's](https://www.grodansparadis.com/) modules and it has it's product page [here](https://www.grodansparadis.com/kelvinntc10k/kelvin_ntc10ka.html). The MDF file for this modules is [here](https://www.eurosource.se/ntc10KA_1.xml).
+
+### Paris relay module
+
+The Paris module is another module from Grodans Paradis AB and it is documented [here](https://www.grodansparadis.com/paris/paris.html). The MDF file for this modules is [here](https://www.eurosource.se/paris_010.xml).
+
+---
+
+## JSON Format Specification
-
-
-
-
-
-
-
-
-`
-
- tttt
-
-
-
- yyyy
- tttt
-
- 3
-
-
- tttt
- yyy
- tttt
-
- tttt
- yyy
- tttt
-
-
-
-`
-
-`
-
-`
-
-`
-
- tttt
- yyy
- tttt
-
-`
-
-``
-
-`` `
- 1
-
- 20
-
- 66
-`
-
-``
-
-``
-
-
-```
-
-**JSON**
-
-Doublets below show different versions of the same tag. For example
+### General JSON format
+
+JSON is a file containing objects and arrays. Each item in an object is a key value pair. Each item in an array is an object item. Values and items can be strings, numbers, booleans or objects. Forming a tree like structure.
```json
-"name": "Name of module",
-"name" : {
- "eng": "English name",
- "swe": "Svensk namn",
- "
+{
+ "redirect": "http://www.example.com/",
+ "module": {
+ ...
+ "manufacturer": {
+ ...
+ },
+ "boot" : {
+ ...
+ },
+ "files" : {
+ "picture" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ],
+ "video" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ],
+ "firmware" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ],
+ "manual" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ],
+ "driver" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ],
+ "setup" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ],
+ },
+ "register" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ],
+ "remotevar" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ],
+ "alarm" : {
+ ...
+ },
+ "dmatrix": {
+ ...
+ },
+ "event" : [
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ]
+ }
}
+
```
-show two ways to enter a _name_, string and object.
+| block | Description |
+| ----- | ----------- |
+| **redirect** | Redirect URL for the module. If it's there the MDF file will not be parsed instead parsaing will be done on the file the redirect url points to. |
+| **module** | Module information. Th erest of thetags are inside the module object. |
+| **manufacturer** | Manufacturer information. |
+| **boot** | Boot information. |
+| **files** | Files information. Picture, Video, firmware, driver, manual and setup files related to the module is defined here. |
+| **register** | Register information is defined here. |
+| **remotevar** | Remote variable information is defined here. |
+| **alarm** | Alarm information. |
+| **dmatrix** | Decission matrix information. |
+| **event** | Event information. |
+
+### A note on JSON file content
+### Descriptions
+Many keys can be defined both as string, number or object. The description key is typical. It can have a value that is a string in which case it is set as an english description. But it can also be an object in which case the language is defined as keys to each description in that language. The language key shall be set as a two character (ISO 639-1 lanuage code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+Like this
+
+```json
+"description": "description in english",
+}
+```
+
+or multilingual as this
+
+```json
+"description" : {
+ "eng": "English description",
+ "swe": "Svensk beskrivning"
+}
+```
Language tags is two letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
----
+### infourl
+
+Info URL's point to a web page that contains information about the item where they are located. The same is tru for them as for descriptions. They can be defined like this
+
+
+```json
+"infourl": "url to info in english ",
+}
+```
+
+or multilingual as this
+
+```json
+"infourl" : {
+ "eng": "English info url",
+ "swe": "Svensk info url"
+}
+```
+Language tags is two letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
+
+### numbers
+
+As JSON can only handle decimal numbers it is possible to define positive numbers as hexadecimal, octal or binary using a string form. If the number has no prefix is will be interpreted as a decimal number, if it has a **0x** prefix it vill be interprested as a hexadecimal number, if it has a **0o** prefix it will be interpreted as an octal number and if it has a **0b** prefix it will be interpreted as a binary number.
+
+ - **12** will be interpreted as a decimal number.
+ - **0xFF00** will be interpreted as a hexadecimal number.
+ - **0o7700** will be interpreted as an octal number.
+ - **0b11010101** will be interpreted as a binary number.
+
+This is only valid for numbers taht is positive. Negative numbers are not supported in this way and must be of numeric type.
+
+## Module
+In the **module**-object the module is described. Currently only one module can be defined in a mdf file. This may change in the future.
+
```json
{
- "vscp": {
-
- "redirect mdf-path": "url",
-
- "modules": [
- {
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "model": "bbbbb",
- "version": "cccccc",
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
-
- "infourl": "https://www.somewhere.com",
- "buffersize": 9999
-
-
- "manufacturer": {
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "address": [
- {
- "street": "ttttttttttttt",
- "town": "llllllllll",
- "city": "London",
- "postcode": "HH1234",
- "state": "state",
- "region": "region",
- "country": "ttttt"
- }
- ]
-
- "telephone": [
- "number": "123456789"
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- ]
-
- "fax": [
- "number": "123456789"
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- ]
-
- "email": [
- "address": "someone@somwhere.com"
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- ]
-
- "web": [
- "address": "https://www.somewhere.com"
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- ]
- },
-
- "driver": [
- {
- "id": "xxx",
- "type": "yyy",
- "os": "zzz",
- "osver": "123",
- "url": "Location for driver"
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- }
- }
- ],
-
- "picture": [
- {
- "path": "url where picture can be found (alternative)",
- "url": "url where picture can be found (alternative)",
- "format": "ext | bmp | jpg | png | ....... ",
- "height": 12345,
- "width": 12345,
- "size": 12345,
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- }
- }
- ],
-
- "firmware" : [
- {
- "path": "url where firmware can be found",
- "url": "url where firmware can be found",
- "format": "intelhex8|intelhex16",
- "size": 123456,
- "date": "ISO date/time when released.",
- "version_major": 12345,
- "version_minor": 12345,
- "version_subminor": 12345,
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- }
- }
- ],
-
- "manual": [
- {
- "path": "url where manual can be found",
- "lang": "Two digit iso code for language",
- "format": "txt | rtf | doc | pdf | html",
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- }
- }
- ]
+ "redirect": "http://www.example.com/",
+ "module" : {
+ ....
+ }
+}
+```
- "abstractions": [
- {
- "id": "some name",
- "type": "bool",
- "default": "false",
- "page": 12345,
- "offset": 12345,
- "bit": 12345,
- "width": 12345,
- "access": "rw",
- "indexed": false,
-
- "name": "Name of abstraction",
- "name" : {
- "gb": "English abstraction name",
- "se": "Svenskt abstraktions namn",
- "lt": "Lietuvos abstrakcija pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url"
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- "valuelist": [
- {
- "value": "value for item",
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- }
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- ]
- }
- ]
-
- "reg": [
- {
- "page": 12345,
- "offset": 12345,
- "default": 12345,
- "access": "rw",
- "bit": [
- {
- "pos": 12345,
- "width": 12345,
- "default": false,
- "name": "Name of bit or bitfield",
- "name" : {
- "gb": "English bit or bitfield name",
- "se": "Svenskt namn för bit eller bitfält",
- "lt": "Lietuva Bitų arba bitų lauko pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url"
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- }
- ],
- "name": "Name of register",
- "name" : {
- "gb": "English register name",
- "se": "Svenskt register namn",
- "lt": "Lietuva registracijos pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "valuelist": [
- {
- "value": "value for item",
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- ]
- }
- ],
-
- "dmatrix": {
- "level": 12345,
- "start": {
- "page": 12345,
- "offset": 12345,
- "indexed": false,
- "rowcount": 12345,
- "rowsize": 12345,
- },
- "action": [
- {
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- "data": [
- "offset": 12345,
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- "bit": [
- "pos": 1234,
- "width": 12345,
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- ]
- ]
- }
- ],
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- },
-
- "events": [
- {
- "class": 12345,
- "type": 12345,
- "direction": "in|out",
- "priority": 12345,
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- "data": [
- "offset": 12345,
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- "bit": [
- "pos": 1234,
- "width": 12345,
- "name": "Name of module",
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- ]
- ]
- }
- ],
-
- "alarm": [
- {
- "pos": 12345,
- "name" : {
- "gb": "English module name",
- "se": "Svenskt modul namn",
- "lt": "Lietuvos modulio pavadinimas"
- },
- "description": "English description",
- "description" : {
- "gb": "English description",
- "se": "Svensk beskrivning",
- "lt": "Lietuvos aprašymas"
- },
- "help": "English text help",
- "help" : {
- "type": "test | url",
- "gb": "English help",
- "se": "Svensk hjälp",
- "lt": "Lietuvos padeda"
- },
- }
- ],
-
- "boot": {
- "algorithm": 1,
- "blocksize" : 20,
- "blockcount": 66
- }
- }
- ]
- }
+| block | Description |
+| ----- | ----------- |
+| **redirect** | Redirect URL for the module. If it's there the MDF file will not be parsed instead parsaing will be done on the file the redirect url points to. |
+| **module** | Module information. Th erest of thetags are inside the module object. |
+| **manufacturer** | Manufacturer information. |
+| **boot** | Boot information. |
+| **files** | Files information. Picture, Video, firmware, driver, manual and setup files related to the module is defined here. |
+| **register** | Register information is defined here. |
+| **remotevar** | Remote variable information is defined here. |
+| **alarm** | Alarm information. |
+| **dmatrix** | Decission matrix information. |
+| **event** | Event information. |
+
+### Redirect
+If set the redirect key should be the first key-pair in the module object. The redirect key can be used to tell the parser to download the MDF from a different URL. If it is defined the file pointed to by the redirect url should be downloaded and parsed instead of the loaded MDF file.
+
+### Module information
+
+Every module should have an initial block that describes the module. This block is called the **General module information**. The block looks like this
+
+```json
+{
+ "module": {
+ "name": "Simple B test",
+ "model": "Simple B model",
+ "version": "B",
+ "changed": "2021-11-02",
+ "description": {
+ "en": "This is an english description",
+ "es": "Esta es una descripción en inglés",
+ "pt": "Esta é uma descrição em inglês",
+ "zh": "这是英文说明",
+ "se": "Det här är en engelsk beskrivning",
+ "lt": "Tai yra angliškas aprašymas",
+ "de": "Dies ist eine englische Beschreibung",
+ "eo": "Ĉi tio estas angla priskribo"
+ },
+ "infourl": {
+ "en": "https://www.english.en",
+ "es": "https://www.spanish.es",
+ "pt": "https://www.portuguese.pt",
+ "zh": "https://www.chineese.zh",
+ "se": "https://www.swedish.se",
+ "lt": "https://www.lithuanian.lt",
+ "de": "https://www.german.de",
+ "eo": "https://www.esperanto.eo"
+ },
+ "buffersize": 8,
+
+ "manufacturer": {
+ "name" : "Grodans Paradis AB",
+ "address": {
+ "street": "Brattbergavägen 17",
+ "city": "Los",
+ "town": "Loos",
+ "postcode": "82770",
+ "state": "HA",
+ "Region": "Hälsingland",
+ "country" : "Sweden"
+ },
+ "telephone": [
+ {
+ "number": "+46 8 40011835",
+ "description": {
+ "en": "Main Reception",
+ "se": "Huvudreception"
+ }
+ }
+ ],
+ "fax": [
+ {
+ "number": "+46 8 40011835",
+ "description": {
+ "en": "Non working fax",
+ "se": "Icke fungerande fax"
+ }
+ }
+ ],
+ "email": [
+ {
+ "address": "support@grodansparadis.com",
+ "description": {
+ "en": "Support email"
+ }
+ },
+ {
+ "address": "sales@grodansparadis.com",
+ "description": "Sales inquires email"
+ },
+ {
+ "address": "info@grodansparadis.com",
+ "
- Output protection timer 0 MSB
-
- This is the most significant byte for the output protection timer.
- An output will be inactivated if not written to before this time
- has elapsed.
- Set to zero to disable (default). The max time is 65535 seconds
- which is about 18 hours.
- The registers can be as an example be used as a security feature
- to ensure that an output
- is deactivated after a preset time even if the controlling device
- failed to deactivate the relay.
-
- rw
-
-
-
- Output protection timer 0 LSB
-
- This is the least significant byte for the output protection timer.
- An output will be inactivated if not written to before this time
- has elapsed.
- Set to zero to disable (default). The max time is 65535 seconds
- which is about 18 hours.
- The registers can be as an example be used as a security feature
- to ensure that an output
- is deactivated after a preset time even if the controlling device
- failed to deactivate the relay.
-
- rw
-
+will create an English, Lithuanian, and a Spanish description. Software that handle languages can then switch between languages fast and efficiently.
+
+#### infourl
+The infourl is an url pointing to a full description of the module in the language given by the **lang** attribute. It is recommended to use a language specific infourl. If no language attribute is given "en" for English will be used. The language code should be a valid two letter (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+As an example
+
+```json
+{
+ "infourl": {
+ "en" : "https://www.somewhere.com",
+ "lt" : "https://www.somewhere.lt",
+ "es" : "https://www.somewhere.es"
+}
```
-As seen the register at position 26 and 27 is used. Both on page 0. A user that gets this information presented for him/here needs to do some calculations to actually set the value. To make it possible to preset this to a user in a more user friendly way and abstraction is defines.
+points to web pages that have info in three different languages.
-```xml
-
- Output protection timer 0
-
- This is the least significant byte for the output protection timer.
- An output will be inactivated if not written to before this time
- has elapsed.\n
- Set to zero to disable (default). The max time is 65535 seconds
- which is about 18 hours.
- The registers can be as an example be used as a security feature
- to ensure that an output
- is deactivated after a preset time even if the controlling device
- failed to deactivate the relay.
-
-
- https://www.vscp.org/wiki/doku.php/modules/nova#output_protection_time_registers
-
- rw
-
+#### buffersize
+For Level II nodes the buffer size specify the max VSCP data a node can receive. This makes it possible to have nodes, that due to low internal resources, that can receive events, but not all events, just those under a specified maximum size. The default is eight bytes which is the data size for a level I node. Set to <= 512 for a level II nodes.
+
+### manufacturer:id=manufacturer_json
+The manufacturer block describes the manufacturer of the module.
+
+#### name
+Name is the name of the company that manufactured the module.
+
+
+#### Address
+The address block looks like this
+
+```json
+{
+ "address": {
+ "street": "Brattbergavägen 17",
+ "city": "Los",
+ "town": "Loos",
+ "postcode": "82770",
+ "state": "HA",
+ "Region": "Hälsingland",
+ "country" : "Sweden"
+ }
+}
```
-Now the two registers instead is presented as an unsigned 16 bit integer in a way a user expect it to be. He/she just set the value in seconds for the protection timer and the control system knowing that an unsigned integer needs two bytes can write or read the value from the register pair 26/27.
+and specify the address to the manufacturer of the module. Use the tags that are appropriate for your project.
-Also here an URL pointing to formatted help information is set. This URL could have been set for the registers as well of course.
-User software first try to present information to users using the definitions in the abstraction section and only use registers if no abstraction covers that register.
+#### Telephone
+This is a phone number of the manufacturer. As many phone numbers as one like can be defined. The format is
+```json
+{
+ "telephone": [
+ {
+ "number": "+46 8 40011835",
+ "description": {
+ "en": "Main Reception",
+ "se": "Huvudreception"
+ }
+ }
+ ]
+}
+```
+The infourl is optional.
-## reg
+#### Fax
+This is a telefax number of the manufacturer. As many fax numbers as one like can be defined. The format is
-### name tag
+```json
+{
+ "fax": [
+ {
+ "number": "+46 8 40011835",
+ "description": {
+ "en": "Non working fax",
+ "se": "Icke fungerande fax"
+ }
+ }
+ ]
+}
+```
+The infourl is optional.
- `register name`
-
-The name tag names the register. This is how the register will be named by handling software. The name tag can have the usual **lang** attribute and there can be one name tag for each supported language.
+#### Email
+This is an email address of the manufacturer. As many email addresses as one like can be defined. The format is
-### description tag
+```json
+{
+ "email": [
+ {
+ "address": "info@vscp.org",
+ "description": {
+ "en": "General email"
+ },
+ "infourl": "https://www.somewhere.com"
+ }
+ ]
+}
+```
+The infourl is optional.
- register name
-
-The description tag describes the register and its use. The description tag can have the usual **lang** attribute and there can be one description tag for each supported language. "\n" can be inserted in text as a new line marker.
+#### Web
+This is a web address of the manufacturer. As many web addresses as one like can be defined. The format is
-### help tag
+```json
+{
+ "web": [
+ {
+ "address": "http://www.vscp.org",
+ "description": {
+ "en": "General web site"
+ },
+ "infourl": "https://www.somewhere.com"
+ }
+ ]
+}
+```
- tttt
-The help tag gives help about the register and its use. The help tag can have the usual **lang** attribute and there can be one help tag for each supported language. The type can be **text** for general inline text help, **html** for inline html help or **url** for an external web page.
-
-### access tag
+The infourl is optional.
- rw
+### boot:id=boot_json
-The access tag is used to tell if a cell is readable or writable or both. **r** is readable and **w** is writable.
-
-### Attributes
-
- | Name | Description |
- | :---- | :----------- |
- | **offset** | Offset (Level I: 0-127) on page this register is located on. |
- | **page** | The page the register is located on. 0-65535 can be set. Default is 0. |
- | **width** | Width expressed as number of bits for register, 0-8. Default is 8. |
- | **default** | Default value for register. Default is 0. |
- | **min** | Minimum value for register. Default is 0. |
- | **max** | Maximum value for register. Default is 255. |
- | **type** | See [register types](./vscp_module_description_file.md&#register_types) below. |
- | **size** | Size (number of registers) for certain types. Default=1. |
- | **fgcolor** | Foreground color for the location this register is presented in. Default is black. Format is **0x//rrggbb//** where **rr** is red value, **gg** is green value, **bb** is blue value or equivalent decimal number. |
- | **bgcolor** | Background color for the location this register is presented in. Default is white. Format is **0x//rrggbb//** where **rr** is red value, **gg** is green value, **bb** is blue value or equivalent decimal number. |
-
-### Register types
-
-For a register tag it is possible to define an optional type attribute. Current possible types is listed in the table below
-
- | Type | Description |
- | :---- | ----------- |
- | **std** | This is a standard register byte. If a type attribute is not present this is what the type will be set as. |
- | **dmatrix1** | This is a level I decision matrix defined a register space. A size attribute is needed which should be set to a value dividable by eight which is the number of rows the decision matrix consist of. *Bitfields and value lists will be ignored.* Se sample below. |
- | **block** | This is a block of registers. A size attribute is needed that specifies the size of the block in bytes. When read a block should be interpreted as **size** register defines with names starting with **name0** to **namen** where n is size-1. The entire block should fit on the same register page. *Bitfields and value lists will be ignored.* Se sample below. |
-
-#### Decision matrix
-
- type="dmatrix1" size="number of dm rows * 8"
-Instead of defining a decision matrix with a register entry for each of its bytes it is possible to define it in a single registry entry. This is done by specifying a type attribute for it set to **dmatrix1**. The registers that build up the decision matrix will be automatically named.
-
-The example
+```json
+{
+ "boot": {
+ "algorithm": 1,
+ "blocksize": 8,
+ "blockcount": 4096,
+ }
+}
+```
-```xml
-
- `Decision matrix``
- Decision matrix for Odessa
-
+The bootloader object specify the bootloader algorithm that should be used to download firmware code to the module. The code for a specific module is defined in standard register *151/0x97*. The possible codes is here [CLASS1.PROTOCOL, Type=12](./class1.protocol.md#id=type12).
+
+Firmware listed in the *Module Description File* file block have a [targetcode](#firmware) as an attribute. This code specify the hardware for a version of the a module the firmware is intended for. Typically the code is different for modules of the same type which have different versions of micro processor, memory, peripherals etc and therefore need different versions of the firmware. A bootloader should read this register and verify the targetcode with the content of the target code registers before loading firmware as loading wrong firmware version can brick a module.
+
+### Files:id=files_json
+
+```json
+{
+ "files": [
+ {
+ ...
+ },
+ ],
+ "video": [
+ {
+ ...
+ }
+ ],
+ "firmware": [
+ {
+ ...
+ }
+ ],
+ "driver": [
+ {
+ ...
+ }
+ ],
+ "manual": [
+ {
+ ...
+ }
+ ],
+ "setup": [
+ {
+ ...
+ }
+ ]
+}
```
+#### picture:id=picture_json
-will generate 64 register entries for a decision matrix that consist of eight rows (64/8) and name them automatically.
+In the picture block you can specify a link to an image file that in some way is related the module and describe it. The format is
+```json
+"files" : [
+ "picture" : [
+ {
+ "url" : "path",
+ "format" : "jpeg",
+ "date" : "ISO date",
+ "version_major" : "a",
+ "version_minor" : "b",
+ "version_subminor" : "c",
+ "url" : "https://www.somewhere.com/picture.jpg",
+ "description" : {
+ "en" : "Description of picture"
+ },
+ "infourl" : {
+ "en" : "htps://www.somewhere.com"
+ }
+ }
+ ]
+]
+```
+Any number of anguage specific descriptions and/or infourl's can be set for each picture item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
-#### Register blocks
+##### Keys
- type="block" size="size of block"
-A register block is a consecutive area of registers that is located on the same page. Naming is done automatically with the register name as a base.
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the picture file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the picture file. |
+| **format** | The format of the picture file. "png", "jpeg" and "jpg" is current valid values. |
-The example
+#### video:id=video_json
-```xml
-
- `Reserved`
- `Reserved for future use.`
-
+In the video block you can specify a link to a video file that in some way is related the module and describe it. The format is
+
+```json
+"files" : [
+ {
+ "video" : [
+ {
+ "url" : "path",
+ "format" : "mp4",
+ "url" : "https://www.somewhere.com/video.mp4",
+ "description" : {
+ "en" : "Description of picture"
+ },
+ "infourl" : {
+ "en" : "htps://www.somewhere.com"
+ }
+ }
+ ]
+ }
+]
```
-
-will generate eight register defines as
-
- | Name | page | offset | Description |
- | ---- | ---- | ------ | ----------- |
- | Reserved0 | 0 | 4 | Reserved for future use. |
- | Reserved1 | 0 | 5 | Reserved for future use. |
- | Reserved2 | 0 | 6 | Reserved for future use. |
- | Reserved3 | 0 | 7 | Reserved for future use. |
- | Reserved4 | 0 | 8 | Reserved for future use. |
- | Reserved5 | 0 | 9 | Reserved for future use. |
- | Reserved6 | 0 | 10 | Reserved for future use. |
- | Reserved7 | 0 | 11 | Reserved for future use. |
-
-## Setup recipes
+Any number of language specific descriptions and/or infourl's can be set for each video item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
-**Preliminary**
+##### Keys
-Setup recipes are stored sequences that can be used to setup a specific device in a certain way. They can just set up a device according to some rules or they can interact with a user
-and setup a device from user input or just guide a user through a specific setup.
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the video file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the video file. |
+| **format** | The format of the video file. "mp4", "mov" and "avi" is current valid values. |
-This is functionality that will be extended heavily in the future.
+#### manual:id=manual_json
-A sample can look like this
+In the manual block you can specify a link to a manual file that in some way is related to the module and describe it. The format is
-```xml
-
-
- Blink-channel0
-
- Set channel 0 to output and blink with 10 Hz.
-
-
-
-
-
-
- `input`
- `Beijing I/O node`
- `With what frequency should channel blink?`
-
-
-
-
-
-
+```json
+"files" : [
+ {
+ "manual" : [
+ {
+ "name" : "driver1",
+ "url" : "path",
+ "format" : "pdf",
+ "url" : "https://www.somewhere.com/manual.pdf",
+ "description" : {
+ "en" : "Description of picture"
+ },
+ "infourl" : {
+ "en" : "htps://www.somewhere.com"
+ }
+ }
+ ]
+ }
+]
```
-
-The recipe has a name which is not multilingual and a description which is multilingual. From this description we see that this recipe will blink channel 0. Names of a recipe can be referenced from other recipes. A name containing spaces will have the spaces replaced by underscores. The description is some informative text for a user.
-Allowed tags are
+Any number of language specific descriptions and/or infourl's can be set for each manual item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Keys
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the video file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the video file. |
+| **format** | The format of the video file. "txt", "md" (markdown), "html" and "pdf" is current valid values. |
+| **lang** | The language of the manual. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6]. |
-
-This sets a bit in a specified register.
+In the driver object you can specify a link to a driver for a specific version of an operation system file that in some way is related the module and describe it. Typically this is a device driver or a VSCP daemon driver or similar. zip and gz packed files are allowed. The format is
-Allowed attributes are
+#### driver:id=driver_json
- | Attributes | Description |
- | ---------- | ----------- |
- | pos | Position in register from low to high (0-7) |
- | page | Page where register is located |
- | offset | Offset in page where register is located |
- | width | Number of bits if this is a bit array. Default = 1 no bitarray. |
- | value | Value for bit. Can either be true/false or 0/1. The value can also be a variable and if so should be preceded with a dollar sign '$'. If width > 1 the value can have a numerical value that fits in width ^ 2. |
-
+```json
+"files": [
+ {
+ "driver": [
+ {
+ "name": "driver1",
+ "url": "path",
+ "type":"mp4",
+ "os": "windows",
+ "osver": 10,
+ "version_major": 1,
+ "version_minor": 0,
+ "version_subminor": 0,
+ "url": "https://www.somewhere.com/driver.zip",
+ "description": {
+ "en": "Description of driver"
+ },
+ "infourl": {
+ "en": "htps://www.somewhere.com"
+ }
+ }
+ ]
+ }
+]
+```
-This sets a bit in a specified abstraction
-
-Allowed attributes are
+Any number of language specific descriptions and/or infourl's can be set for each driver item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
- | Attributes | Description |
- | ---------- | ----------- |
- | name | Name of abstraction |
- | pos | Position in register from low to high. |
- | width | Number of bits if this is a bit array. Default = 1 no bitarray. |
- | value | Value for bit. Can either be true/false or 0/1. The value can also be a variable and if so should be preceded with a dollar sign '$'. |
+##### Keys
-
-
-This sets a value in a register
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the video file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the video file. |
+| **os** | The operating system. Examples are "Debian Linux", "Microsoft Windows" etc |
+| **osver** | The version of the operating system. Examples are "10", "8.1" etc |
+| **version_major** | Major version number for driver. |
+| **version_minor** | Minor version number for driver. |
+| **version_subminor** | Sub minor version number for driver. |
+| **md5** | MD5 checksum for the driver file as hexadecimal string. Empty if not used. |
- | Attributes | Description |
- | ---------- | ----------- |
- | page | Page where register is located |
- | offset | Offset in page where register is located |
- | value | Value for bit. Can either be true/false or 0/1. The value can also be a variable and if so should be preceded with a dollar sign '$'. |
+#### setup:id=setup_json
-
-
-This sets a value of an abstraction
+In the setup block you can specify a link to a setup file that contain a VSCP setup script that do a specific setup of the device. The format is
+
+```json
+"files" : [
+ {
+ "setup" : [
+ {
+ "name" : "setup1",
+ "url" : "path",
+ "format" : "pdf",
+ "url" : "https://www.somewhere.com/setup.js",
+ "description": {
+ "en": "Description of driver"
+ },
+ "infourl": {
+ "en": "htps://www.somewhere.com"
+ }
+ }
+ ]
+ }
+]
+```
+
+Any number of language specific descriptions and/or infourl's can be set for each setup item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+##### Keys
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. |
+| **url** | The url from which the video file can be fetched. |
+| **path** | (Deprecated alternative to "url"). The url to the video file. |
+| **format** | The format of the setup file. "vscpjs" for VSCP javascript setup is the only current valid value. |
+
+### Register:id=register_json
+
+```json
+{
+ "register" : [
+ {
+ ...
+ }
+ {
+ ...
+ }
+ {
+ ...
+ }
+ ]
+}
+```
+
+All defined registers of a module is defined in the registers block. The format is
+
+```json
+{
+ "register" : [
+ {
+ "name" : "symbolic name for register. Should be unique.",
+ "page" : "The page that contains the register",
+ "offset" : "offset to register in the page",
+ "type" : "'std'(default)/'block'/'dmatrix1'",
+ "span" : "Number of registers for 'block' an 'dmatrix1' types. Default = 1",
+ "width" : "Width in bits for register (1-8 bits). Default = 8",
+ "size" : "(Deprecated) Size in bytes for register. Default = 1",
+ "min" : "Minimum value for register. Default = 0",
+ "max" : "Maximum value for register. Default = 255",
+ "access" : "r/w/rw",
+ "default": "VSCP Works specific: Default value in string form. Default is 'UNDEF'",
+ "fgcolor": "VSCP Works specific: foreground color",
+ "bgcolor" : "VSCP Works specific: background color",
+ "description" : [
+ "en" : "Description of register"
+ ],
+ "infourl" : [
+ "en" : "Link to url that have language specific information about the register"
+ ]
+ }
+ ]
+}
+```
+
+#### Keys
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the item. Should be unique.|
+| **page** | The page on whish the register is located. |
+| **offset** | The zero based offset on the page where the register is defined. Level I: 0-127. Level II: 0-0xFFFFFFFE |
+| **type** | Specify the register type. A register is by default defined as 'std' which is a standard register. But 'block' can be used for a consecutive number of registers. Another form is 'dmatrix1' which is the standard level I decision matrix. For the non standard form span tells the number of registers used in the block and the full decision matrix |
+| **span** | Number of bytes for the register. This defaults to one as expected. But for the 'block' and the 'dmatrix1' types it tell the number of consecutive bytes used. Both 'block' and 'dmatrix1' types of registers will get names specified from the name attribute with a incrementing number appended for each register (name1, name2, name3...) |
+| **width** | Can be used to limit the registers bit width from 8-1. Default is eight. |
+| **size** | (Deprecated. Do not use) Size in bytes for register. Default = 1 |
+| **min** | Minimum value for register. Default = 0 |
+| **max** | Maximum value for register. Default = 255 |
+| **access** | Specify the access rights for the register. Can be 'r' (read), 'w' (write) or 'rw' (read/write. Default is 'rw' |
+| **default** | VSCP Works specific: Default value in string form. Default is 'UNDEF' Used by VSCP Works to restore default value to a register. |
+| **fgcolor** | VSCP Works specific: foreground color. Used as foreground color by VSCP Works when rendering this register row. |
+| **bgcolor** | VSCP Works specific: background color. Used as background color by VSCP Works rendering this register row. |
+
+Any number of language specific descriptions and/or infourl's can be set for each register item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+Numeric values can be set as a numeric value or as a string. The string can be defined as a hexadecimal value (prefix: 0x, a decimal (no prefix), an octal value (prefix: 0o) or a binary value (prefix: 0b).
+
+#### Value lists
+
+Registers can have valuelists taht define valid possible values
+
+```json
+"valuelist" : [
+ {
+ "value" : "0x00",
+ "name" : "Off",
+ "description" : {
+ "en" : "The device is off",
+ "se" : "Enheten är av"
+ },
+ "infourl" : {
+ "gb": "English help url",
+ "se": "Svensk hjälp url",
+ "lt": "Lietuvos padeda url"
+ }
+ },
+ {
+ "value" : "0x01",
+ "name" : "On",
+ "description" : {
+ "en" : "The device is on",
+ "se" : "Enheten är på"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ }
+ },
+ {
+ "value" : "0xff",
+ "name" : "Disabled",
+ "description" : {
+ "en" : "Device is disabled",
+ "se" : "Enheten är avstängd"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ }
+ }
+]
+```
+
+#### Bit fields
+
+Registers can have bit fields that define bits and groups of bits of the register. It is possible to use value lists for bit groups.
+
+```json
+"bit": [
+ {
+ "pos": 0,
+ "width": 1,
+ "default": 0,
+ "min": 0,
+ "max": 7,
+ "access" : "rw",
+ "name" : "English bit or bitfield name 0",
+ "description" : {
+ "gb": "English description bitfield 0",
+ "se": "Svensk beskrivning bitfield 0",
+ "lt": "Lietuvos aprašymas bitfield 0"
+ },
+ "infourl" : {
+ "gb": "English help bitfield 0",
+ "se": "Svensk hjälp bitfield 0",
+ "lt": "Lietuvos padeda bitfield 0"
+ },
+ "valuelist" : [
+ {
+ "value" : "0x00",
+ "name" : "Off",
+ "description" : {
+ "en" : "The device is off",
+ "se" : "Enheten är av"
+ },
+ "infourl" : {
+ "gb": "English help url",
+ "se": "Svensk hjälp url",
+ "lt": "Lietuvos padeda url"
+ }
+ },
+ {
+ "value" : "0x01",
+ "name" : "On",
+ "description" : {
+ "en" : "The device is on",
+ "se" : "Enheten är på"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ }
+ },
+ {
+ "value" : "0x07",
+ "name" : "Disabled",
+ "description" : {
+ "en" : "Device is disabled",
+ "se" : "Enheten är avstängd"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ }
+ }
+
+ ]
+ },
+ {
+ "pos": "0x03",
+ "width": "0x02",
+ "default": false,
+ "access": "r",
+ "min": "0x01",
+ "max": "0x07",
+ "name" : "English bit or bitfield name 1",
+ "description" : {
+ "gb": "English description bitfield 1",
+ "se": "Svensk beskrivning bitfield 1",
+ "lt": "Lietuvos aprašymas bitfield 1"
+ },
+ "infourl" : {
+ "gb": "English help bitfield 1",
+ "se": "Svensk hjälp bitfield 1",
+ "lt": "Lietuvos padeda bitfield 1"
+ }
+ }
+]
+```
- | Attributes | Description |
- | ---------- | ----------- |
- | name | Name of abstraction |
- | value | Value that is valid for the type of the abstraction. The value can also be a variable and if so should be preceded with a dollar sign '$'. |
+#### Example
-
+```json
+{
+ "register" : [
+ {
+ "page": 2,
+ "offset": "0x22",
+ "span": 1,
+ "width": 8,
+ "min" : 2,
+ "max" : 128,
+ "access" : "rw",
+ "default": 99,
+ "rowpos" : 11,
+ "bgcolor" : "0xfff3d4",
+ "fgcolor" : "0x001200",
+ "name" : "Register example 1",
+ "description" : {
+ "en" : "Just a byte register with color settings",
+ "se" : "Ett vanligt register med färginställningar"
+ },
+ "infourl" : {
+ "en" : "https://one.com",
+ "se" : "https://two.com"
+ }
+ },
+ {
+ "page": "0x02",
+ "offset": "0x31",
+ "default": "0x88",
+ "width": "0x04",
+ "span": "0x01",
+ "min" : "0x00",
+ "max" : "0x000f",
+ "access" : "r",
+ "default": "0xfd",
+ "rowpos" : "0xaa",
+ "bgcolor" : "0x00f3d4",
+ "fgcolor" : "0x100000",
+ "name" : "Register example 2",
+ "description" : {
+ "en" : "Register with value list",
+ "se" : "Beskrivning med värde lista"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ },
+ "valuelist" : [
+ {
+ "value" : "0x00",
+ "name" : "Off",
+ "description" : {
+ "en" : "The device is off",
+ "se" : "Enheten är av"
+ },
+ "infourl" : {
+ "gb": "English help url",
+ "se": "Svensk hjälp url",
+ "lt": "Lietuvos padeda url"
+ }
+ },
+ {
+ "value" : "0x01",
+ "name" : "On",
+ "description" : {
+ "en" : "The device is on",
+ "se" : "Enheten är på"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ }
+ },
+ {
+ "value" : "0xff",
+ "name" : "Disabled",
+ "description" : {
+ "en" : "Device is disabled",
+ "se" : "Enheten är avstängd"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ }
+ }
+ ]
+ },
+ {
+ "name" : "Register example 3",
+ "page": 99,
+ "offset": 2,
+ "default": "0x55",
+ "width" : 8,
+ "span" : 3,
+ "type" : "block",
+ "min" : 0,
+ "max" : 255,
+ "access" : "w",
+ "rowpos" : "200",
+ "bgcolor" : "0xfffff3d4",
+ "fgcolor" : "0xffffffff",
+ "description" : {
+ "en" : "Register with bits",
+ "se" : "Beskrivning med bitar"
+ },
+ "infourl" : {
+ "gb": "English help bits",
+ "se": "Svensk hjälp bits",
+ "lt": "Lietuvos padeda bits"
+ },
+ "bit": [
+ {
+ "pos": 0,
+ "width": 3,
+ "default": 4,
+ "min": 0,
+ "max": 7,
+ "access" : "rw",
+ "name" : "English bit or bitfield name 0",
+ "description" : {
+ "gb": "English description bitfield 0",
+ "se": "Svensk beskrivning bitfield 0",
+ "lt": "Lietuvos aprašymas bitfield 0"
+ },
+ "infourl" : {
+ "gb": "English help bitfield 0",
+ "se": "Svensk hjälp bitfield 0",
+ "lt": "Lietuvos padeda bitfield 0"
+ }
+ },
+ {
+ "pos": "0x03",
+ "width": "0x02",
+ "default": false,
+ "access": "r",
+ "min": "0x01",
+ "max": "0x07",
+ "name" : "English bit or bitfield name 1",
+ "description" : {
+ "gb": "English description bitfield 1",
+ "se": "Svensk beskrivning bitfield 1",
+ "lt": "Lietuvos aprašymas bitfield 1"
+ },
+ "infourl" : {
+ "gb": "English help bitfield 1",
+ "se": "Svensk hjälp bitfield 1",
+ "lt": "Lietuvos padeda bitfield 1"
+ }
+ }
+ ]
+ },
+ {
+ "name" : "Register example 4",
+ "page": 12,
+ "offset": 22,
+ "span":128,
+ "type": "dmatrix1"
+ }
+ ]
+ }
+}
+```
+
+### Remote variables:id=remotevars_json
+
+```json
+{
+ "remotevar" : [
+ {
+ ...
+ }
+ {
+ ...
+ }
+ {
+ ...
+ }
+ ]
+}
+```
+and each remote variable object looks like
+
+```json
+"remotevars" : [
+ {
+ "name" : "remotevariable1",
+ "type" : "uint16_t",
+ "default" : "1234",
+ "page": 0,
+ "offset": 19,
+ "access" : "r",
+ "fgcolor" : "0x112233" ,
+ "bgcolor" : "0xE0E0FF",
+ "description" : [
+ {
+ "en": "Remote variable description.",
+ "se": "Beskrivning av variable."
+ }
+ ],
+ "infourl": [
+ {
+ "en": "Remote var url en",
+ "se": "Variabel url se"
+ }
+ ]
+ }
+]
+```
+
+
+Remote variables or *abstractions*, as they was named in previous versions of the VSCP specification, is a higher level view of register space. Here we look at the storage using well known variable typers such as stings, integers and floats. This makes it easier to use the register values in a configuration script etc.
+
+All remote variables are mapped into register space and are stored there big endian, that is with the high byte in the first byte. An 16-bit integer will accordingly be stored with the MSB byte in the first register and the LSB in the second byte and so on.
+
+There is no need to define remote variables for bytes as they are already defined in the register space. Automatic remote variables will be created for registers that do not have a remote variable defined. These will be named as follows:
+
+
+_rv__
+
+So for example if you have a register named "Reg1" then the remote variable will be named "_rv_reg1_".
+
+Needless to say names with this pattern are reserved.
+#### Keys
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the remote variable. |
+| **type** | A type for the remote variable. Remote variable types are [here](./vscp_register_abstraction_model.md#remote-variables). |
+| **page** | The page where the remote variable is stored. |
+| **offset** | The offset off the page where the MSB of the remote variable is stored. |
+| **bitpos** | The bit of a register used for a boolean. If not set and the type is boolean bit 0 will be used. No meaning for other types. |
+| **size** | The size of a remote variable that is of type string. The size is the max size of the buffer. |
+| **access** | Specify the access rights for the remote variable. Can be 'r' (read), 'w' (write) or 'rw' (read/write. Default is 'rw' |
+
+In the same way as registers remote variables can also have valuelists and bit fields. See docs above.
+
+#### Example with valuelist
+
+```json
+"remotevar" : [
+ {
+ "name" : "Remote variable 1",
+ "type": "short",
+ "default":"8",
+ "access": "rw",
+ "page" :"2",
+ "offset" :18,
+ "rowpos": 99,
+ "bgcolor" :"0xCCFFFF",
+ "fgcolor" :"0x123456",
+
+ "description" : {
+ "en": "English description remotevar 1",
+ "se": "Svensk beskrivning remotevar 1",
+ "lt": "Lietuvos padeda remotevar 1"
+ },
+ "infourl" : {
+ "gb": "English help remotevar 1",
+ "se": "Svensk hjälp remotevar 1",
+ "lt": "Lietuvos padeda remotevar 1"
+ }
+ },
+ {
+ "name" : "Remote variable 2",
+ "type": "uint8",
+ "default": "0x22",
+ "access": "r",
+ "page" : "0x11",
+ "offset" :"12",
+ "rowpos": "0x04",
+ "bgcolor" :"0x777777",
+ "fgcolor" :"0x888888",
+ "description" : {
+ "en": "English description remotevar 2",
+ "se": "Svensk beskrivning remotevar 2",
+ "lt": "Lietuvos padeda remotevar 2"
+ },
+ "infourl" : {
+ "en": "English help remotevar 2",
+ "se": "Svensk hjälp remotevar 2",
+ "lt": "Lietuvos padeda remotevar 2"
+ },
+ "valuelist" : [
+ {
+ "value" : "0x00",
+ "name" : "Low",
+ "description" : {
+ "en" : "Low speed",
+ "se" : "Låg hastighet",
+ "lt" : "??????????"
+ },
+ "infourl" : {
+ "gb": "English help 1 vl2",
+ "se": "Svensk hjälp 1 vl2",
+ "lt": "Lietuvos padeda 1 vl2"
+ }
+ },
+ {
+ "value" : "0x01",
+ "name" : "Medium",
+ "description" : {
+ "en" : "Medium speed",
+ "se" : "Medium hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 2 vl2",
+ "se": "Svensk hjälp 2 vl2",
+ "lt": "Lietuvos padeda 2 vl2"
+ }
+ },
+ {
+ "value" : "0x03",
+ "name" : "High",
+ "description" : {
+ "en" : "High speed",
+ "se" : "Hög hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 3 vl2",
+ "se": "Svensk hjälp 3 vl2",
+ "lt": "Lietuvos padeda 3 vl2"
+ }
+ }
+ ]
+ },
+ {
+ "name" : "Remote variable 3",
+ "type": "uint32",
+ "default":"0",
+ "access": "rw",
+ "page" :"9",
+ "offset" :98,
+ "rowpos": "0x44",
+ "bgcolor" :"0x999999",
+ "fgcolor" :"0xAAAAAA",
-This displays a message box which can be of several types. It can be used to inform a user about different things and it can be used to input information from a user.
+ "description" : {
+ "en": "English description 3",
+ "se": "Svensk beskrivning 3",
+ "lt": "Lietuvos padeda 3"
+ },
+ "infourl" : {
+ "gb": "English help 3",
+ "se": "Svensk hjälp 3",
+ "lt": "Lietuvos padeda 3"
+ },
+ "bit": [
+ {
+ "pos": 0,
+ "width": 3,
+ "default": 4,
+ "min": 0,
+ "max": 7,
+ "access" : "rw",
+ "name" : "Bitfield name 0",
+ "description" : {
+ "gb": "English description bitfield 0",
+ "se": "Svensk beskrivning bitfield 0",
+ "lt": "Lietuvos aprašymas bitfield 0"
+ },
+ "infourl" : {
+ "gb": "English help bitfield 0",
+ "se": "Svensk hjälp bitfield 0",
+ "lt": "Lietuvos padeda bitfield 0"
+ }
+ },
+ {
+ "pos": 3,
+ "width": 2,
+ "default": false,
+ "access": "r",
+ "name" : "Bitfield name 1",
+ "description" : {
+ "gb": "English description bitfield 1",
+ "se": "Svensk beskrivning bitfield 1",
+ "lt": "Lietuvos aprašymas bitfield 1"
+ },
+ "infourl" : {
+ "gb": "English help bitfield 1",
+ "se": "Svensk hjälp bitfield 1",
+ "lt": "Lietuvos padeda bitfield 1"
+ },
+ "valuelist" : [
+ {
+ "value" : "0x00",
+ "name" : "Low",
+ "description" : {
+ "en" : "Low speed",
+ "se" : "Låg hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 1 vl2",
+ "se": "Svensk hjälp 1 vl2",
+ "lt": "Lietuvos padeda 1 vl2"
+ }
+ },
+ {
+ "value" : "0x01",
+ "name" : "Medium",
+ "description" : {
+ "en" : "Medium speed",
+ "se" : "Medium hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 2 vl2",
+ "se": "Svensk hjälp 2 vl2",
+ "lt": "Lietuvos padeda 2 vl2"
+ }
+ },
+ {
+ "value" : "0x03",
+ "name" : "High",
+ "description" : {
+ "en" : "High speed",
+ "se" : "Hög hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 3 vl2",
+ "se": "Svensk hjälp 3 vl2",
+ "lt": "Lietuvos padeda 3 vl2"
+ }
+ }
+ ]
+ }
+ ]
+ }
+]
+```
-The following messagebox types are defined.
- | Type | function textual identifier | function numerical identifier | Description |
- | ---- | --------------------------- | ----------------------------- | ----------- |
- | Information | "info" | 0 | Give some textual information with an OK button |
- | Input | "input" | 1 | Input a string into a variable |
- | Valuelist | "list" | 2 | Let a user selects an item from a list setting a variable to a value related to the list item |
- | Checkbox | "checkbox" | 3 | Let the user select among a couple of options in check boxes and returns named variables that are set or not set for each option. Many can be selected. |
- | Radiobox | "radiobox" | 4 | Let the user select among a couple of options in radio boxes and returns one named variable that have a value specified by the option. Only one can be selected. |
+### Alarms:id=alarm_json
- | Attributes | Description |
- | ---------- | ----------- |
- | function | Either a textual function or a numerical function identifier which selects what messagebox to display |
- | head | Text to display in header of message box. Can have **lang** attribute to specify language. |
- | description | Text to display as description in message box. \n can be used as a new line. Can have **lang** attribute to specify language. |
- | icon | Select icon to be used |
- | variable | Select a variablename that is coupled to messagebox and which will receve input. Can have a **type** attribute and value checking will occure if so. A string is always returned. |
+```json
+"alarm" [
+ {
+ "pos": "7",
+ "name": "Reserved7",
+ "description": [
+ {
+ "en": "Reserved 7"
+ }
+ ],
+ "infourl": [
+ {
+ "en": "https://www.somewhere.com/info7.html"
+ }
+ ]
+ }
+ {
+ "pos": "6",
+ "name": "Reserved6",
+ "description": [
+ {
+ "en": "Reserved 6"
+ }
+ ],
+ "infourl": [
+ {
+ "en": "https://www.somewhere.com/info6.html"
+ }
+ ]
+ }
+ {
+ "pos": "5",
+ "name": "Reserved5",
+ "description": [
+ {
+ "en": "Reserved 5"
+ }
+ ],
+ "infourl": [
+ {
+ "en": "https://www.somewhere.com/info5.html"
+ }
+ ]
+ }
+ {
+ "pos": "4",
+ "name": "Reserved4",
+ "description": [
+ {
+ "en": "Reserved 4"
+ }
+ ],
+ "infourl": [
+ {
+ "en": "https://www.somewhere.com/info4.html"
+ }
+ ]
+ }
+ {
+ "pos": "3",
+ "name": "Reserved3",
+ "description": [
+ {
+ "en": "Reserved 3"
+ }
+ ],
+ "infourl": [
+ {
+ "en": "https://www.somewhere.com/info3.html"
+ }
+ ]
+ }
+ {
+ "pos": "2",
+ "name": "Reserved2",
+ "description": [
+ {
+ "en": "Reserved 2"
+ }
+ ],
+ "infourl": [
+ {
+ "en": "https://www.somewhere.com/info2.html"
+ }
+ ]
+ }
+ {
+ "pos": "1",
+ "name": "HighAlarm",
+ "description": [
+ {
+ "en": "High alarm. The value of one of the A/D channels has gone above the high alarm level."
+ }
+ ],
+ "infourl": [
+ {
+ "en": "https://www.somewhere.com/info2.html"
+ }
+ ]
+ }
+ {
+ "pos": "0",
+ "name": "LowAlarm",
+ "description": [
+ {
+ "en": "Low alarm. The value of one of the A/D channels has gone under the low alarm level."
+ }
+ ],
+ "infourl": [
+ {
+ "en": "https://www.somewhere.com/info2.html"
+ }
+ ]
+ }
+]
+```
-## Setup screens
+The alarm block specify the meaning of the alarm bits in the standard alarm register [128/0x80](./vscp_register_abstraction_model.md#register_abstraction_model). In the block there is a bit filed of max eight bit definitions each describing the alarm bits of the register. You just need to specify the bits that is used.
-**Preliminary**
+#### Keys
-This is just preliminary information about a future UI element that can be used to configure and/or control a module. There are two types of this type of interfaces
+| Name | Description |
+| :---- | :----------- |
+| **name** | A name for the alarm bit. |
-### Live setup screens
+Any number of language specific descriptions and/or infourl's can be set for each register item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
-A live setup screen is a pointer to a web page that can be used to setup/control the VSCP module that is described in the MDF file. The module can either a module that is attached to a VSCP daemon interfaces or a full Level II module. It is the users responsibility to point the setup code to the right interface with the help of discovery procedures. There can be as many pointers to ui setup interfaces as needed.
-The format for the tag is
+### Decision Matrix:id=dm_json
+
+```json
+"dmatrix" : {
+ "level" : 1,
+ "start-page" : "0x10",
+ "start-offset": 88,
+ "rowcount" : 10,
+ "rowsize" : 8,
+ "action": [
+ {
+ "name": "action 1",
+ "code": "0x01",
+ "description" : {
+ "en": "English description dm action 1",
+ "se": "Svensk beskrivning dm action 1",
+ "lt": "Lietuvos padeda dm action 1"
+ },
+ "infourl" : {
+ "en": "English help dm action 1",
+ "se": "Svensk hjälp dm action 1",
+ "lt": "Lietuvos padeda dm action 1"
+ },
+ "param": [
+ {
+ "name" : "parm 1",
+ "description" : {
+ "en": "English description dm param 1",
+ "se": "Svensk beskrivning dm param 1",
+ "lt": "Lietuvos padeda dm param 1"
+ },
+ "infourl" : {
+ "en": "English help dm param 1",
+ "se": "Svensk hjälp dm param 1",
+ "lt": "Lietuvos padeda dm param 1"
+ }
+ }
+ ]
+ }
+ ]
+}
-```xml
-
- Bla. bla. bla. bla.
- If url is empty base64 encoded ui content here
-
```
-or
+If the module have a [decision matrix](./vscp_decision_matrix.md) it can be defined here. You specify where in the register space the decision matrix is located and the numer of rows for the matrix. The decision matrix holds an array of actions. Each row in the matrix is a row in the register space. The actions are defined in the action block.
-```xml
-
- Bla. bla. bla. bla.
-
-```
+For a level I decision matrix there is one and only one parameter for each action. For Level II decision matrixes however there can be several (defined by the attribute *rowsize*). In both cases the parameter(s) is described in the param block.
-where the later points to a list with entries of the former type.
+#### Keys dmatrix
-### Package setup screens
+| Name | Description |
+| :---- | :----------- |
+| **level** | Decision matrix level 1/2. Default=1. |
+| **start-page** | The page where the decision matrix is stored in register space. |
+| **start-offset** | The offset of the register page where the decision matrix is stored. |
+| **rowcnt** | Number of decision matrix rows. |
+| **rowsize** | Number of decision matrix bytes on each row. For a level I decision matrix this is always eight. Default=8. |
-This type is a package in a zip file with JavaScript code/HTML5/CSS that defines a setup UI. The package should have a structure in the zip file that is the same as it should have on disc. A manifest in the file in XML format specify the content.
+#### Keys action
-The format for the tag is
+| Name | Description |
+| :---- | :----------- |
+| **name** | Name for the action. |
+| **code** | The numerical code for the action (0-255). |
-```xml
-
- ``Bla. bla. bla. bla.
- `If url is empty base64 encoded content here
-
+#### Keys action parameter
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | Name for the action parameter. |
+| **offset** | Parameter field offset. Always zero for level I decision matrix as it always have only one parameter. Default = 0 |
+| **min** | Minimum value for the parameter. Default = 0. |
+| **max** | Maximum value for the parameter. Default = 255. |
+
+Any number of language specific descriptions and/or infourl's can be set for each register item. If no language attribute is given "en" for English will be used. The language code should be a valid two letter code (ISO 639-1 code)[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes6].
+
+#### Example
+
+```json
+"dmatrix" : {
+ "level" : 1,
+ "start-page" : "0x10",
+ "start-offset": 88,
+ "indexed": false,
+ "rowcount" : 10,
+ "rowsize" : 8,
+ "action": [
+ {
+ "name": "action 1",
+ "code": "0x01",
+ "description" : {
+ "en": "English description dm action 1",
+ "se": "Svensk beskrivning dm action 1",
+ "lt": "Lietuvos padeda dm action 1"
+ },
+ "infourl" : {
+ "en": "English help dm action 1",
+ "se": "Svensk hjälp dm action 1",
+ "lt": "Lietuvos padeda dm action 1"
+ },
+ "param": [
+ {
+ "name" : "parm 1",
+ "description" : {
+ "en": "English description dm param 1",
+ "se": "Svensk beskrivning dm param 1",
+ "lt": "Lietuvos padeda dm param 1"
+ },
+ "infourl" : {
+ "en": "English help dm param 1",
+ "se": "Svensk hjälp dm param 1",
+ "lt": "Lietuvos padeda dm param 1"
+ },
+ "bit": [
+ {
+ "name" : "Bitfield name 0",
+ "pos": 0,
+ "width": 3,
+ "default": 7,
+ "min": 0,
+ "max": 7,
+ "access" : "rw",
+ "description" : {
+ "gb": "English description",
+ "se": "Svensk beskrivning",
+ "lt": "Lietuvos aprašymas"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ }
+ },
+ {
+ "name" : "Bitfield name 1",
+ "pos": 3,
+ "width": 2,
+ "default": false,
+ "description" : {
+ "gb": "English description",
+ "se": "Svensk beskrivning",
+ "lt": "Lietuvos aprašymas"
+ },
+ "infourl" : {
+ "gb": "English help",
+ "se": "Svensk hjälp",
+ "lt": "Lietuvos padeda"
+ },
+ "valuelist" : [
+ {
+ "value" : "0x00",
+ "name" : "Low",
+ "description" : {
+ "en" : "Low speed",
+ "se" : "Låg hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 1 vl2",
+ "se": "Svensk hjälp 1 vl2",
+ "lt": "Lietuvos padeda 1 vl2"
+ }
+ },
+ {
+ "value" : "0x01",
+ "name" : "Medium",
+ "description" : {
+ "en" : "Medium speed",
+ "se" : "Medium hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 2 vl2",
+ "se": "Svensk hjälp 2 vl2",
+ "lt": "Lietuvos padeda 2 vl2"
+ }
+ },
+ {
+ "value" : "0x03",
+ "name" : "High",
+ "description" : {
+ "en" : "High speed",
+ "se" : "Hög hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 3 vl2",
+ "se": "Svensk hjälp 3 vl2",
+ "lt": "Lietuvos padeda 3 vl2"
+ }
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "name" : "parm 2",
+ "description" : {
+ "en": "English description dm param 2",
+ "se": "Svensk beskrivning dm param 2",
+ "lt": "Lietuvos padeda dm param 2"
+ },
+ "infourl" : {
+ "en": "English help dm param 2",
+ "se": "Svensk hjälp dm param 2",
+ "lt": "Lietuvos padeda dm param 2"
+ }
+ }
+ ]
+ },
+ {
+ "name": "action 2",
+ "code": "0x02",
+ "description" : {
+ "en": "English description dm action 2",
+ "se": "Svensk beskrivning dm action 2",
+ "lt": "Lietuvos padeda dm action 2"
+ },
+ "infourl" : {
+ "gb": "English help dm action 2",
+ "se": "Svensk hjälp dm action 2",
+ "lt": "Lietuvos padeda dm action 2"
+ },
+ "parm": [
+ {
+ "name" : "parm 2",
+ "description" : {
+ "en": "English description dm param 1",
+ "se": "Svensk beskrivning dm param 1",
+ "lt": "Lietuvos padeda dm param 1"
+ },
+ "infourl" : {
+ "gb": "English help dm param 1",
+ "se": "Svensk hjälp dm param 1",
+ "lt": "Lietuvos padeda dm param 1"
+ },
+ "valuelist" : [
+ {
+ "value" : "0x00",
+ "name" : "Low",
+ "description" : {
+ "en" : "Low speed",
+ "se" : "Låg hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 1 vl2",
+ "se": "Svensk hjälp 1 vl2",
+ "lt": "Lietuvos padeda 1 vl2"
+ }
+ },
+ {
+ "value" : "0x01",
+ "name" : "Medium",
+ "description" : {
+ "en" : "Medium speed",
+ "se" : "Medium hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 2 vl2",
+ "se": "Svensk hjälp 2 vl2",
+ "lt": "Lietuvos padeda 2 vl2"
+ }
+ },
+ {
+ "value" : "0x02",
+ "name" : "High",
+ "description" : {
+ "en" : "High speed",
+ "se" : "Hög hastighet"
+ },
+ "infourl" : {
+ "gb": "English help 3 vl2",
+ "se": "Svensk hjälp 3 vl2",
+ "lt": "Lietuvos padeda 3 vl2"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
```
-or
-```xml
-
- Bla. bla. bla. bla.
-
+### Events:id=events_json
+
+```json
+"events" : [
+ {
+ "name": "test event 1",
+ "class" : 10,
+ "type": 6,
+ "direction": "in",
+ "priority": "low",
+ "description" : {
+ "en": "English event description 3",
+ "se": "Svensk event beskrivning 3",
+ "lt": "Lietuvos event padeda 3"
+ },
+ "infourl" : {
+ "en": "English event help 3",
+ "se": "Svensk event hjälp 3",
+ "lt": "Lietuvos event padeda 3"
+ },
+ "data" : [
+ {
+ "name": "test event data 1",
+ "description" : {
+ "en": "English event data description 3",
+ "se": "Svensk event data beskrivning 3",
+ "lt": "Lietuvos event data padeda 3"
+ },
+ "infourl" : {
+ "en": "English event data help 3",
+ "se": "Svensk event data hjälp 3",
+ "lt": "Lietuvos event data padeda 3"
+ }
+ },
+ {
+ ...
+ },
+ {
+ ...
+ }
+ ]
+ },
+ {
+ ...
+ }
+]
+```
+
+In the *event* object events that the module can receive and handle is described but maybe even more importantly events that the module send out itself can be 34 described. A *data* block is defined for each data byte of the event describing it.
+
+For data blocks bit fields and value lists can be used. See description above for more information.
+
+#### Keys for event
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | Name for the event. |
+| **class** | Event class. Mandatory. Can be set to '-' whish means all classes. |
+| **type** | Event type. Mandatory. Can be set to '-' whish means all types. |
+| **priority** | Priority for the event. Default=3. |
+| **dir** | Direction of event. "in" is incoming event. "out" is outgoing event. Default="out" |
+
+#### Keys for event data
+
+| Name | Description |
+| :---- | :----------- |
+| **name** | Name for the event data byte. |
+| **offset** | Data byte offset. |
+
+Event data can use value lists and bit fields. See description above for more information.
+
+#### Example
+
+```json
+"events" : [
+ {
+ "name": "test event 1",
+ "class" : 10,
+ "type": 6,
+ "direction": "in",
+ "priority": "low",
+ "description" : {
+ "en": "English event description 3",
+ "se": "Svensk event beskrivning 3",
+ "lt": "Lietuvos event padeda 3"
+ },
+ "infourl" : {
+ "en": "English event help 3",
+ "se": "Svensk event hjälp 3",
+ "lt": "Lietuvos event padeda 3"
+ },
+ "data" : [
+ {
+ "name": "test event data 1",
+ "description" : {
+ "en": "English event data description 3",
+ "se": "Svensk event data beskrivning 3",
+ "lt": "Lietuvos event data padeda 3"
+ },
+ "infourl" : {
+ "en": "English event data help 3",
+ "se": "Svensk event data hjälp 3",
+ "lt": "Lietuvos event data padeda 3"
+ },
+ "bit": [
+ {
+ "pos": 0,
+ "width": 3,
+ "default": 4,
+ "min": 0,
+ "max": 7,
+ "access" : "rw",
+ "name" : "Bitfield name 0",
+ "description" : {
+ "en": "English description bit 0",
+ "se": "Svensk beskrivning bit 0",
+ "lt": "Lietuvos aprašymas bit 0"
+ },
+ "infourl" : {
+ "en": "English help bit 0",
+ "se": "Svensk hjälp bit 0",
+ "lt": "Lietuvos padeda bit 0"
+ }
+ },
+ {
+ "pos": 3,
+ "width": 2,
+ "access" : "r",
+ "default": false,
+ "name" : "Bitfield name 1",
+ "description" : {
+ "en": "English description bit 1",
+ "se": "Svensk beskrivning bit 1",
+ "lt": "Lietuvos aprašymas bit 1"
+ },
+ "infourl" : {
+ "en": "English help bit 1",
+ "se": "Svensk hjälp bit 1",
+ "lt": "Lietuvos padeda bit 1"
+ },
+ "valuelist" : [
+ {
+ "value" : "0x00",
+ "name" : "Low",
+ "description" : {
+ "en" : "Low speed",
+ "se" : "Låg hastighet"
+ },
+ "infourl" : {
+ "en": "English help 1 vl2",
+ "se": "Svensk hjälp 1 vl2",
+ "lt": "Lietuvos padeda 1 vl2"
+ }
+ },
+ {
+ "value" : "0x01",
+ "name" : "Medium",
+ "description" : {
+ "en" : "Medium speed",
+ "se" : "Medium hastighet"
+ },
+ "infourl" : {
+ "en": "English help 2 vl2",
+ "se": "Svensk hjälp 2 vl2",
+ "lt": "Lietuvos padeda 2 vl2"
+ }
+ },
+ {
+ "value" : "0x03",
+ "name" : "High",
+ "description" : {
+ "en" : "High speed",
+ "se" : "Hög hastighet"
+ },
+ "infourl" : {
+ "en": "English help 3 vl2",
+ "se": "Svensk hjälp 3 vl2",
+ "lt": "Lietuvos padeda 3 vl2"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+]
```
-where the later points to a list with entries of the former type.
+## Real life MDF XML formatted file examples
+
+Some example files can be found [here](https://github.com/grodansparadis/vscp/tree/development/tests/mdfparser/json).
-the `` tag is for devices that have the capability to have large information on-board, and in this case the ui packet is delivered inside the mdf.
## Resources
+ * [VSCP MDF parser library](https://github.com/grodansparadis/vscp-mdf-parser-lib)
+ * [VSCP Works](https://github.com/grodansparadis/vscp-works-qt)
* [Howto: Get MDF content in JSON or JSONP format](https://grodansparadis.com/wordpress/?p=1492)
* [Howto: Read MDF content with node.js](https://grodansparadis.com/wordpress/?p=3984)
diff --git a/vscp_register_abstraction_model.md b/vscp_register_abstraction_model.md
index c917195..5774b60 100644
--- a/vscp_register_abstraction_model.md
+++ b/vscp_register_abstraction_model.md
@@ -20,54 +20,52 @@ The page read/write, boot events etc can handle more then eight data bytes if th
The VSCP registers are defined as follows:
-##### Register abstraction model
-
- | Address | Access Mode | Description |
- | ------- | ----------- | ----------- |
- | 0x00–0x7F | — | Device specific (a page). Unimplemented registers should return zero. |
- | 128/0x80 | Read Only | Alarm status register content (!= 0 indicates alarm). Condition is reset by a read operation. The bits represent different alarm conditions. |
- | 129/0x81 | Read Only | VSCP Major version number this device is constructed for. |
- | 130/0x82 | Read Only | VSCP Minor version number this device is constructed for. |
- | 131/0x83 | Read/Write | VSCP error counter (was Node control flags prior to 1.6) |
- | 132/0x84 | Read/Write | User ID 0 – Client settable node-ID byte 0. |
- | 133/0x85 | Read/Write | User ID 1 – Client settable node-ID byte 1. |
- | 134/0x86 | Read/Write | User ID 2 – Client settable node-ID byte 2. |
- | 135/0x87 | Read/Write | User ID 3 – Client settable node-ID byte 3. |
- | 136/0x88 | Read/Write | User ID 4 – Client settable node-ID byte 4. |
- | 137/0x89 | Read only | Manufacturer device ID byte 0. |
- | 138/0x8A | Read only | Manufacturer device ID byte 1. |
- | 139/0x8B | Read only | Manufacturer device ID byte 2. |
- | 140/0x8C | Read only | Manufacturer device ID byte 3. |
- | 141/0x8D | Read only | Manufacturer sub device ID byte 0. |
- | 142/0x8E | Read only | Manufacturer sub device ID byte 1. |
- | 143/0x8F | Read only | Manufacturer sub device ID byte 2. |
- | 144/0x90 | Read only | Manufacturer sub device ID byte 3. |
- | 145/0x91 | Read only | Nickname-ID for node if assigned or 0xFF if no nickname-ID assigned. |
- | 146/0x92 | Read/Write | Page select register MSB |
- | 147/0x93 | Read/Write | Page Select register LSB |
- | 148/0x94 | Read Only | Firmware major version number. |
- | 149/0x95 | Read Only | Firmware minor version number. |
- | 150/0x96 | Read Only | Firmware sub minor version number. |
- | 151/0x97 | Read Only | Boot loader algorithm used. 0xFF for no boot loader support. Codes for algorithms are specified here [CLASS1.PROTOCOL, Type=12](./class1.protocol#id=type12) |
- | 152/0x98 | Read Only | Buffer size. The value here gives an indication for clients that want to talk to this node if it can support the larger mid level Level I control events which has the full GUID. If set to 0 the default size should used. That is 8 bytes for Level I and 512-25 for Level II. |
- | 153/0x99 | Read Only | Number of register pages used. If not implemented one page is assumed. Set to zero if your device have more then 255 pages. **Deprecated**: Use the MDF instead as the central place for information about actual number of pages. |
- | 154/0x9A | Read Only | Standard device family code (MSB) Devices can belong to a common register structure standard. For such devices this describes the family coded as a 32-bit integer. Set all bytes to zero if not used. Also 0xff is reserved and should be interpreted as zero was read. *Added in version 1.9.0 of the specification* |
- | 155/0x9B | Read Only | Standard device family code *Added in version 1.9.0 of the specification* |
- | 156/0x9C | Read Only | Standard device family code *Added in version 1.9.0 of the specification* |
- | 157/0x9D | Read Only | Standard device family code (LSB) *Added in version 1.9.0 of the specification* |
- | 158/0x9E | Read Only | Standard device type (MSB) This is part of the code that specifies a device that adopts to a common register standard. This is the type code represented by a 32-bit integer and defines the type belonging to a specific standard. *Added in version 1.9.0 of the specification* |
- | 159/0x9F | Read Only | Standard device type *Added in version 1.9.0 of the specification* |
- | 160/0xA0 | Read Only | Standard device type *Added in version 1.9.0 of the specification* |
- | 161/0xA1 | Read Only | Standard device type (LSB) *Added in version 1.9.0 of the specification* |
- | 162/0xA2 | Write Only | Standard configuration should be restored for a unit if first 0x55 and then 0xAA is written to this location and is done so withing one second. *Added in version 1.10.0 of the specification* |
- | 163/0xA3-207/0xCF | — | Reserved for future use. Return zero. |
- | 208/0xD0-223/0xDF | Read Only | 128-bit (16-byte) globally unique ID (GUID) identifier for the device. This identifier uniquely identifies the device throughout the world and can give additional information on where driver and driver information can be found for the device. MSB for the identifier is stored first (in 0xD0). |
+##### Register abstraction model:id=register_abstraction_model
+
+ | Address | Access Mode | Description |
+ | ------- | ----------- | ----------- |
+ | 0x00–0x7F | | Device specific (a page). Unimplemented registers should return zero. |
+ | 128/0x80 | Read Only | Alarm status register content (!= 0 indicates alarm). Condition is reset by a read operation. The bits represent different alarm conditions. |
+ | 129/0x81 | Read Only | VSCP Major version number this device is constructed for. |
+ | 130/0x82 | Read Only | VSCP Minor version number this device is constructed for. |
+ | 131/0x83 | Read/Write | VSCP error counter (was Node control flags prior to 1.6) |
+ | 132/0x84 | Read/Write | User ID 0 – Client settable node-ID byte 0. |
+ | 133/0x85 | Read/Write | User ID 1 – Client settable node-ID byte 1. |
+ | 134/0x86 | Read/Write | User ID 2 – Client settable node-ID byte 2. |
+ | 135/0x87 | Read/Write | User ID 3 – Client settable node-ID byte 3. |
+ | 136/0x88 | Read/Write | User ID 4 – Client settable node-ID byte 4. |
+ | 137/0x89 | Read only | Manufacturer device ID byte 0. |
+ | 138/0x8A | Read only | Manufacturer device ID byte 1. |
+ | 139/0x8B | Read only | Manufacturer device ID byte 2. |
+ | 140/0x8C | Read only | Manufacturer device ID byte 3. |
+ | 141/0x8D | Read only | Manufacturer sub device ID byte 0. |
+ | 142/0x8E | Read only | Manufacturer sub device ID byte 1. |
+ | 143/0x8F | Read only | Manufacturer sub device ID byte 2. |
+ | 144/0x90 | Read only | Manufacturer sub device ID byte 3. |
+ | 145/0x91 | Read only | Nickname-ID for node if assigned or 0xFF if no nickname-ID assigned. |
+ | 146/0x92 | Read/Write | Page select register MSB |
+ | 147/0x93 | Read/Write | Page Select register LSB |
+ | 148/0x94 | Read Only | Firmware major version number. |
+ | 149/0x95 | Read Only | Firmware minor version number. |
+ | 150/0x96 | Read Only | Firmware sub minor version number. |
+ | 151/0x97 | Read Only | Boot loader algorithm used. 0xFF for no boot loader support. Codes for algorithms are specified here [CLASS1.PROTOCOL, Type=12](./class1.protocol#id=type12) |
+ | 152/0x98 | Read Only | Buffer size. The value here gives an indication for clients that want to talk to this node if it can support the larger mid level Level I control events which has the full GUID. If set to 0 the default size should used. That is 8 bytes for Level I and 512-25 for Level II. |
+ | 153/0x99 | Read Only | Number of register pages used. If not implemented one page is assumed. Set to zero if your device have more then 255 pages. **Deprecated**: Use the MDF instead as the central place for information about actual number of pages. |
+ | 154/0x9A | Read Only | Standard device family code (MSB) Devices can belong to a common register structure standard. For such devices this describes the family coded as a 32-bit integer. Set all bytes to zero if not used. Also 0xff is reserved and should be interpreted as zero was read. *Added in version 1.9.0 of the specification* |
+ | 155/0x9B | Read Only | Standard device family code *Added in version 1.9.0 of the specification* |
+ | 156/0x9C | Read Only | Standard device family code *Added in version 1.9.0 of the specification* |
+ | 157/0x9D | Read Only | Standard device family code (LSB) *Added in version 1.9.0 of the specification* |
+ | 158/0x9E | Read Only | Standard device type (MSB) This is part of the code that specifies a device that adopts to a common register standard. This is the type code represented by a 32-bit integer and defines the type belonging to a specific standard. *Added in version 1.9.0 of the specification* |
+ | 159/0x9F | Read Only | Standard device type *Added in version 1.9.0 of the specification* |
+ | 160/0xA0 | Read Only | Standard device type *Added in version 1.9.0 of the specification* |
+ | 161/0xA1 | Read Only | Standard device type (LSB) *Added in version 1.9.0 of the specification* |
+ | 162/0xA2 | Write Only | Standard configuration should be restored for a unit if first 0x55 and then 0xAA is written to this location and is done so withing one second. *Added in version 1.10.0 of the specification* |
+ | 163/0xA3 | Read Only | Firmware device code MSB. *Added in version 1.13.0 of the specification* |
+ | 164/0xA4 | Read Only | Firmware device code LSB. *Added in version 1.13.0 of the specification* |
+ | 165/0xA5-207/0xCF | — | Reserved for future use. Return |
+ | 208/0xD0-223/0xDF | Read Only | 128-bit (16-byte) globally unique ID (GUID) identifier for the device. This identifier uniquely identifies the device throughout the world and can give additional information on where driver and driver information can be found for the device. MSB for the identifier is stored first (in 0xD0). |
| 224/0xE0-255/0xFF | Read Only | Module Description File URL. A zero terminates the ASCII string if not exactly 32 bytes long. The URL points to a file that gives further information about where drivers for different environments are located. Can be returned as a zero string for devices with low memory. It is recommended that unimplemented registers read as 0xFF. For a node with an embedded MDF return a zero string. The CLASS1.PROTOCOL, Type=34/35 can then be used to get the information if available. |
-
-
-
-
### User ID
This is a register space that can be used to store installation values as for example a location code of where the unit is installed.
@@ -86,6 +84,14 @@ Added in version 1.9.0 of the specification
Some devices has a need for a common register structure standard. This is defined by two 32-bit values in the standard register space. The family value defines the group of devices the module belongs to and the type value describes the specific device type in that family it belongs to. Families and device types are still to be defined.
+### Firmware device code
+
+Added in version 1.13.0 of the specification
+
+The firmware code is used to distinguish a device type of a module from one another so that the correct firmware can be loaded to a module. Typically a board have different firmware codes here for different microprocessors used as reversions of the board is shipped over time. The firmware code can be given in the MDF file and makes it possible to prevent the wrong firmware being loaded to a module.
+
+Return zero if not used.
+
## Level II - Register Abstraction Model
The level II abstraction model is the same as Level I but covers a much wider address space.
@@ -94,68 +100,57 @@ The registers are laid out in an 32-bit address space with the standard Level I
-## Abstractions
+## Remote variables (Abstractions):id=remote-variables
-A VSCP unit is describing it's configuration to the world with the register model above where each register is eight bit in width. This is often inconvenient for a human user who is used to higher level types and this is what *abstractions* are there for. They sit above registers and specify types as strings, floats, integers and other such higher level types.
+**Note:** Remote variables where called *abstractions* in previous versions (1.13) of the specification.
-Just as register definitions, abstractions live there life in the [Module Description file (MDF)](./vscp_module_description_file.md).
+A VSCP device is describing it's configuration to the world with the register model described above where each register is eight bit in width. This is often inconvenient for a human user who is used to higher level types and this is what *remote variables* is defined for. They sit above registers and specify higher level types as strings, floats, integers and other such higher level types.
-The following abstractions are currently defined
+Just as register definitions, remote variables live there life in the [Module Description file (MDF)](./vscp_module_description_file.md).
- | Abstraction | Description |
- | ----------- | ----------- |
- | string | A text string (UTF8 coded) |
- | bitfield | A field of bits. Width tells how many bits the field consist of. When read from a device the number of bits will always be in even octets with unused bits set to zero. Bitfield is taken from MSB part thrue LSB and continues that way on next octet in the series. |
- | bool | A 1 bit number specified as true or false. |
- | int8_t | An 8 bit number. Hexadecimal if it starts with "0x" else decimal. |
- | uint8_t | An unsigned 8 bit number. Hexadecimal if it starts with "0x" else decimal. |
- | int16_t | A 16 bit signed number. Hexadecimal if it starts with "0x" else decimal. |
- | uint16_t | A 16 bit unsigned number. Hexadecimal if it starts with "0x" else decimal. |
- | int32_t | A 32 bit signed number. Hexadecimal if it starts with "0x" else decimal. |
- | uint32_t | A 32 bit unsigned number. Hexadecimal if it starts with "0x" else decimal. |
- | int64_t | A 64 bit signed number. Hexadecimal if it starts with "0x" else decimal. |
- | uint64_t | A 64 bit unsigned number. Hexadecimal if it starts with "0x" else decimal. |
- | float | Data is coded as a IEEE-754 1985 floating point value That is a total of 32-bits. The most significant byte is stored first. |
- | double | IEEE-754, 64 Bits, double precision. That is a total of 64-bits. The most significant byte is stored first. |
- | date | Must be passed in the format dd-mm-yyyy and mapped to "yy yy mm dd" that is four bytes, MSB->LSB |
- | time | Must be passed in the format hh:mm:ss where hh is 24 hour clock and mapped to "hh mm ss" MSB->LSBthat is four bytes. |
- | guid | Holds the 16 bytes of a GUID. Stored on the form 11:22:33:... MSB->LSB |
+The following remote variables are currently defined
+
+ | Remote variable | Description |
+ | ----------- | ----------- |
+ | string | A text string (UTF8 coded). Can be indexed. See below. |
+ | bool | A 1 bit value specified as true or false. |
+ | int8_t | A 8 bit signed number. Hexadecimal if it starts with "0x" else decimal. |
+ | uint8_t | An unsigned 8 bit number. Hexadecimal if it starts with "0x" else decimal. |
+ | int16_t | A 16 bit signed number. Hexadecimal if it starts with "0x" else decimal. |
+ | uint16_t | A 16 bit unsigned number. Hexadecimal if it starts with "0x" else decimal. |
+ | int32_t | A 32 bit signed number. Hexadecimal if it starts with "0x" else decimal. |
+ | uint32_t | A 32 bit unsigned number. Hexadecimal if it starts with "0x" else decimal. |
+ | int64_t | A 64 bit signed number. Hexadecimal if it starts with "0x" else decimal. |
+ | uint64_t | A 64 bit unsigned number. Hexadecimal if it starts with "0x" else decimal. |
+ | float | Data is coded as a IEEE-754 1985 floating point value That is a total of 32-bits. The most significant byte is stored first. |
+ | double | IEEE-754, 64 Bits, double precision. That is a total of 64-bits. The most significant byte is stored first. |
+ | date | Must be passed in the format dd-mm-yyyy and mapped to "yy yy mm dd" that is four bytes, MSB->LSB |
+ | time | Must be passed in the format hh:mm:ss where hh is 24 hour clock and mapped to "hh mm ss" MSB->LSBthat is four bytes. |
A note on floating point numbers and storage (source Wikipedia)
*"Although the ubiquitous x86 of today use little-endian storage for all types of data (integer, floating point, BCD), there have been a few historical machines where floating point numbers were represented in big-endian form while integers were represented in little-endian form." ... "However, on modern standard computers (i.e., implementing IEEE 754), one may in practice safely assume that the endianness is the same for floating point numbers as for integers, making the conversion straightforward regardless of data type."*
+The following remote variables has been removed as of version 1.13 of the VSCP specification
+ | Remote variable | Description |
+ | ----------- | ----------- |
+ | bitfield | A field of bits. Width tells how many bits the field consist of. When read from a device the number of bits will always be in even octets with unused bits set to zero. Bitfield is taken from MSB part thrue LSB and continues that way on next octet in the series. |
+ | guid | Holds the 16 bytes of a GUID. Stored on the form 11:22:33:... MSB->LSB |
### synonyms
- | Abstraction | Description |
+ | Remote variable | Description |
| ----------- | ----------- |
| char | Is the same as "int8_t". |
| byte | Is the same as "uint8_t". |
| short | Is the same as "int16_t". |
| integer | Is the same as "int16_t". |
| long | Is the same as "int32_t". |
-
-### index storage
-
-This type of storage takes up two bytes in register space. The first byte is the index into the second.
-
- | Abstraction | Description |
- | ----------- | ----------- |
- | index8_int16_t | 16-bit signed integer |
- | index8_uint16_t | unsigned 16-bit integer |
- | index8_int32_t | 32-bit signed integer |
- | index8_uint32_t | 32-but unsigned integer |
- | index8_int64_t | 64-bit signed integer |
- | index8_uint64_t | 64-bit unsigned integer |
- | index8_float | 32-bit floating point value |
- | index8_double | 64-bit floating point value |
- | index8_date | "date" see above. |
- | index8_time | "time" see above |
- | index8_guid | "guid" see above |
- | index8_string | UTF8 string stored as [width, string]. Width tells how long the strings are. If any of them are shorter then this value it should be zero terminated. |
+ | ulong | Is the same as "uint32_t".|
+### indexed storage
+In versions prior to 1.13 of the specification all remote variables with a size > 2 could be stored indexed. This is only true for the *string* type from version 1.13. An indexed string is stored in two bytes in register space. Index (0-255) in the first byte and the value for the indexed position of the string in the second byte.
[filename](./bottom_copyright.md ':include')
diff --git a/vscp_specification_history.md b/vscp_specification_history.md
index d782645..caa041a 100644
--- a/vscp_specification_history.md
+++ b/vscp_specification_history.md
@@ -2,7 +2,10 @@
| Date | By | Description |
| ---------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | 2021-10-05 | AKHE | Updated clas definitions to latest. |
+ | 2022-01-21 | AKHE | Added proper description of JSON formatted MDF files. |
+ | 2022-01-17 | AKHE | Two new standard register positions has been added for 'firmware code' |
+ | 2022-01-13 | AKHE | Updated MDF info. 'abstraction' has been changed to 'remotevar'. 'abstraction' can still be used. 'name' attribute is not language dependent anymore. |
+ | 2021-10-05 | AKHE | Updated class definitions to latest. |
| 2021-09-06 | AKHE | Clarified CLASS1_MEASUREMENT, VSCP_TYPE_MEASUREMENT_ANGLE |
| 2021-08-03 | AKHE | CLASS1.INFORMATION, Type=88, VSCP_TYPE_INFORMATION_PROXIMITY_DETECTED now have standard data content. |
| 2021-06-21 | AKHE | Alarm reset event added. |