Module Description File
The VSCP registers 0xe0-0xff specifies the Module Description File URL (without “http:” which
is implied). The file is in XML 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.
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.
Coding: UTF-8
===== Real life file samples =====
example1 - eurosource Kelvin SHT sensor - http://www.eurosource.se/sht_001.xml
example2 - eurosource Kelvin Smart2 sensor - http://www.eurosource.se/smart2_001.xml
===== XML Format Specification =====
Notes
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
registeroffset
for example
register1
register40
The type will always be “uint8_t” in this case
“\n” can be used for a new line in text.
<code xml>
<?xml version = “1.0” encoding = “UTF-8” ?>
<!– Version 0.0.5 2008-10-24
“string” - Text string
“bitfield” - a field of bits. Width tells how many bits the field consist if (max eight bits).
“bool” - 1 bit number specified as true or false
“int8_t” - 8 bit number. Hexadecimal if it starts with “0x” else decimal
“uint8_t” - Unsigned 8 bit number. Hexadecimal if it starts with “0x” else decimal
“int16_t” - 16 bit signed numbr. Hexadecimal if it starts with “0x” else decimal
“uint16_t” - 16 bit unsigned number. Hexadecimal if it starts with “0x” else decimal
“int32_t” - 32 bit signed numbr. Hexadecimal if it starts with “0x” else decimal
“uint32_t” - 32 bit unsigned number. Hexadecimal if it starts with “0x” else decimal
“int64_t” - 64 bit signed number. Hexadecimal if it starts with “0x” else decimal
“uint64_t” - 64 bit unsigned number. Hexadecimal if it starts with “0x” else decimal
“decimal” - 128 bit number. Hexadecimal if it starts with “0x” else decimal
“date” - Must be passed in the format dd-mm-yyyy
“time” - Must be passed in the format hh:mm:ss where hh is 24 hour clock
–>
<!– General section –>
<vscp>
<module> <!– one file can contain one or several modules –>
<name>aaaaaaaa</name>
<model>bbbbb</model>
<version>cccccc</version>
<description lang = “en”>yyyyyyyyyyyyyyyyyyyyyyyyyyyy</description>
<!– Site with info about the product –>
<infourl>http://www.somewhere.com</infourl>
<!– Max package size a node can receive –>
<buffersize></buffersize>
<manufacturer>
<name>tttttttttttttttttttt</name>
<address>
<street>ttttttttttttt</street>
<town>llllllllll</town>
<city>London</city>
<postcode>HH1234</postcode>
<!– Use region or state –>
<state></state>
<region></region>
<country>ttttt</country>
</address>
<!– One or many –>
<telephone>
<number>123456789</number>
<description lang=“en” >Main Reception</description>
</telephone>
<!– One or many –>
<fax>
<number>1234567879</number>
<description lang=“en”>Main Fax Number</description>
</fax>
<!– One or many –>
<email>
<address>someone@somwhere.com</description>
<description> lang=“en”>Main email address</description>
</email>
<!– One or many –>
<web>
<address>www.somewhere.com</address>
<description lang=“en”>Main web address</address>
</web>
</manufacturer>
<!– Available Drivers
id is a manufacturer defined id for the driver
type is “canal” or “vscp”
os is “linux-generic”, “mac-generic”, “windows-generic”, “windows-nt”, “windows-xp”, “windows-vista”
osver is os version
–>
<driver id=“xxx”, type=“yyy” os=“zzz” osver=“123”>
<description lang=“en”>Main email address</description>
<location>Where the driver can be fetched from (one or many)</location>
</driver>
<!– Settings Section
Types are defined here. An abstraction is something that maps to a register which is
specified by page/offset and is of a predefined type
The id is the tag that can be used in Level II configuration events.
–>
<abstractions>
<!–
The abstract variable “somename” is defined as a boolean type which can have a value 0 or 1
(system also recognize false/true). This variable is located at page=0, offset=1 at bit=0. As this is a
boolean the system knows it ocupies one bit. Other types may need “width” to be defined also. The variable
can be read and written.
Note that the name of the “variable” can be set to different thing depending on locale.
Note the difference between “id” and “name”. “id” is the same for a certain abstraction for all languages
and what is used internally by system software. “name” is what is presented to the user.
–>
<abstraction id=“somename”
type=“bool”
default=“false” page = “0” offset = “1” bit=“0” >
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
<access>rw</access>
</abstraction>
<!–
The abstract variable “alsoaname” is just defined as a short. That is a 16-bit signed integer.
It has a default value of 182 and is located at page=0 offset=15 and 16 (Bigendian). The variable can be
read and written.
–>
<abstraction id=“alsoaname”
type=“short”
default=“182” page = “0” offset = “15” >
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
<access>rw</access>
</abstraction>
<!–
Here a abstract variable “adescriptivename” of type string is defined. A width is needed here and the
string is stored in page=0 at offset=20-21. Read write access is possible
–>
<abstraction id=“adescriptivename”
type=“string”
width=“12”
default=”” page = “0” offset = “20” >
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
<access>rw</access>
</abstraction>
<!–
This example shows a valuelist stored in an integer. This is typically presented to the user as
a listbox or a combobox with values to choose from.
If register space is limited it can be more efficient to use a bitfield for the options.
–>
<abstraction id=“namedlist”
type=“integer”
default=”” page = “0” offset = “100” >
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
<access>r</access>
<valuelist>
<item value = “0×0”>
<name lang=“en”>item0</name>
<description lang=“en”>item0_description</description>
</item>
<item value = “0×1”>
<name lang=“en”>item1</name>
<description lang=“en”>item1_description</description>
</item>
<item value = “0×2”>
<name lang=“en”>item2</name>
<description lang=“en”>item2_description</description>
</item>
<item value = “0×3”>
<name lang=“en”>item3</name>
<description lang=“en”>item3_description</description>
</item>
<item value = “0×4”>
<name lang=“en”>“item4</name>
<description lang=“en”>item4_description</description>
</item>
<item value = “0×5”>
<name lang=“en”>item5</name>
<description lang=“en”>item5_description</description>
</item>
<item value = “0×6”>
<name lang=“en”>item6</name>
<description lang=“en”>item6_description</description>
</item>
<item value = “0×7”>
<name lang=“en”>item7</name>
<description lang=“en”>item7_description</description>
</item>
<item value = “0×8”>
<name lang=“en”>item8</name>
<description lang=“en”>item8_description</description>
</item>
</valuelist>
</abstraction>
</abstractions>
<!– Register section –>
<registers>
<!– The following is abstraction “alsoaname”
described in register space by two reg items.
–>
<reg page=“0” offset=“15” default=“0” >
<name lang=“en”>alsoaname_msb</name>
<description lang=“en”>MSB of alsoaname</description>
<help type=“text/url” lang=“en”>tttt</help>
<access>rw</access>
</reg>
<reg page=“0” offset=“16” >
<help type=“text/url” lang=“en”>tttt</help>
<name lang=“en”>alsoaname_lsb</name>
<description lang=“en”>LSB of alsoaname</description>
<access>rw</access>
</reg>
<!– The following is abstraction “adescriptivename”
described in register space. Note the use of “width”
which can be used to tell how many registers an abstraction
see instead of having many register defines. Default width
is one byte.
–>
<reg page=“0” offset=“15” width=“12” >
<help type=“text/url” lang=“en”>tttt</help>
<name lang=“en”>abcdefghih</name>
<description lang=“en”>The string adescriptivename</description>
<access>rw</access>
</reg>
<!–
This example shows how individual bits in a register is defined. Note that each bit can be named.
Note also at pos 4 (a bit position) where a bit field has been defined which is four bits wide. Here
a valuelist also could have been defined describing the possible values.
All eight bites in register at page=0, offset=1 is described here.
–>
<reg page=“0” offset=“1” >
<help type=“text/url” lang=“en”>tttt</help>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<access>rw</access>
<bit pos=“0” default=“false” >
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</bit>
<bit pos=“1”>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</bit>
<bit pos=“2”>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</bit>
<bit pos=“3”>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</bit>
<bit pos=“4” width=“4”> <!– example for bit groups –>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</bit>
</reg>
<!–
Here a bitfield with width of six bits has been defined. Note the access rights for the field. If
access rights is not given read+write access is presumed.
The register iteself is not give a name here just the bit field.
–>
<reg page=“0” offset=“2”>
<bit pos=“2” width=“6”>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
<access>rw</access>
<valuelist>
<item value = “0×0”>
<name lang=“en”>undefined</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×1”>
<name lang=“en”>Normal</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×2”>
<name lang=“en”>Error</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×3”>
<name lang=“en”>Disabled</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×4”>
<name lang=“en”>“Test</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×5”>
<name lang=“en”>Disposed</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×6”>
<name lang=“en”>PowerSaving</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×7”>
<name lang=“en”>Stopped</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×8”>
<name lang=“en”>Paused</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
</valuelist>
</bit>
</reg>
<!–
Here all bits of a register is used as a value list which is only readable.
–>
<reg page = “0” offset = “88”>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
<access>r</access>
<valuelist>
<item value = “0×0”>
<name lang=“en”>undefined</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×1”>
<name lang=“en”>Normal</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×2”>
<name lang=“en”>Error</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×3”>
<name lang=“en”>Disabled</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×4”>
<name lang=“en”>“Test</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×5”>
<name lang=“en”>Disposed</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×6”>
<name lang=“en”>PowerSaving</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×7”>
<name lang=“en”>Stopped</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
<item value = “0×8”>
<name lang=“en”>Paused</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</item>
</valuelist>
</reg>
<!– Example where min/max is used –>
<reg page = “0” offset = “88” min=“8” max=“32”>
<name lang=“en”>Trust</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</reg>
</registers>
<!– Decison matrix –>
<dmatrix>
<help type=“text/url” lang=“en”>tttt</help>
<!– Can durrently be 1 or 2 –>
<level>1</level>
<!– Where is matrix located –>
<start page=“0” offset=“1”/>
<!– # of rows in matrix –>
<rowcnt>10</rowcnt>
<!– Size in bytes for one row - only for level II –>
<rowsize></rowsize>
<!– Code for action !–>
<action code=“0×0”>
<name lang=“en”></name>
<description lang=“en”></description>
<help type=“text/url” lang=“en”>tttt</help>
<!– Descriptions of parameters - one or many –>
<param>
<name lang=“en”></name>
<description lang=“en”></description>
<help type=“text/url” lang=“en”>tttt</help>
<!– Just one pos for Level I –>
<data offset=“1” >
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
<bit pos=“0”>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</bit>
<!– valuelist could also be used in bit groups and for hole byte –>
</data>
</param>
</action>
</dmatrix>
<!– Events this module can generate –>
<events>
<event class=“0” type=“10” >
<help type=“text/url” lang=“en”>tttt</help>
<!– Optional: user event name –>
<name lang=“en”></name>
<!– Why and when event is sent –>
<description lang=“en”></description>
<help type=“text/url” lang=“en”>tttt</help>
<!– Optional: What priority it will be sent as –>
<priority>3</priority>
<!– Information about evenet data –>
<data offset=“1” >
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
<bit pos=“0”>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</bit>
</data>
</event>
</events>
<!– A valuelist can be used here as well –>
<!– Description/specification for alarm bits –>
<alarm>
<bit pos=“1”>
<name lang=“en”>tttt</name>
<description lang=“en”>yyy</description>
<help type=“text/url” lang=“en”>tttt</help>
</bit>
</alarm>
<!– bootlader information –>
<boot>
<!– bootloader algorithm tha can be used on this module –>
<algorithm>1</algorithm>
<!– Size of boot block/sector –>
<blocksize>20</blocksize>
<!– Number of available boot blocks/sectors –>
<blockcount>66</blockcount>
</boot>
</module>
</vscp>
</code>
Discussion