This is the original class and type specification for VSCP. Documents and source files are generated from this info. The 'scripts' folder holds scripts to generate different output.
The current autogenerated files can be found here https://github.com/grodansparadis/vscp-classes
The folder classes holds class definitions as xml files with the following structure
<class id="0"
name="VSCP Protocol Functionality"
token="CLASS1.PROTOCOL"
alternative-token="other token"
events="n">
<type id="12"
name="Enter boot loader mode."
token="" />
</class><events> used when this class have the same events as anohter class n.
<alternative-token> used to set an alternative token.
0.md hoilds class description in Markdown format 0.n.md holds description for types of this class.
Links to other classes should have this format
[CLASS1.INFORMATION, Type=9 (HEARTBEAT)](./class1.information.md#type9)
A structure
<render>
<vscpworks template="......." />
</render>holds one or more mustache named templates used to display information about an events dynamic data content. The first template defined is vscpworks. This template is used to display HTML based info about an event. The event is used as argument when the mustache expression is parsed. Meaning all parts of the event can be used. So for example {{vscpData[0]}} is data byte 0, vscpClass is the class, vscpGuid is the GUID and so on. A typical example is this visualization for CLASS1.MEASUREMENT
<vscpworks template="<b>Unit: </b> = {{unitstr}} [{{unit}}]<br> <b>Sensorindex: </b> = {{sensorindex}}<br> <b>Value: </b> = {{val}}{{symbol-utf8}}<br>"
/>The measurement class (10) has a <unit> token that is used to describe units. Attributes are
- name Name for the unit.
- description Description of the unit.
- symbol-ascii Symbol in ASCII format
- symbol-utf8 Symbol in UTF8 format
- conversion Conversion code to convert a value of the specific unit to a value of unit 0. Javascript mustache format is used as pseudo code for the conversion and value is specified as {{val}} in this code. mathjs is used to parse the expression after mustache parser is run. Set to {{val}} if a conversion is not possible.
This is how this looks for the temperature measurement type
<type id="6" name="Temperature" token="VSCP_TYPE_MEASUREMENT_TEMPERATURE" >
<units>
<unit id="0"
name="kelvin"
description="Degrees Kelvin"
symbol-ascii="K"
symbol-utf8="K"
conversion="{{val}}"/>
<unit id="1"
name="celsius"
description="Degrees Celsius"
symbol-ascii="C"
symbol-utf8="°C"
conversion="{{val}} + 273.15 "/>
<unit id="2"
name="fahrenheit"
description="Degrees Fahrenheit"
symbol-ascii="F"
symbol-utf8="°F"
conversion="({{val}} + 459.67) * 5/9"/>
</units>
</type>Note that unit can be in the interval 0-255 as class=10 is used to describe also Level II measurement classes. For Level I classes only unit 0-3 is valid of course.
- classes - VSCP class and type definitions.
- scripts - Python scripts that generate output
- cheaders - templates for c-headers.
- python - Templates for Python.
- javascript - Templates for JavaScript.
- db - Templates for VSCP database.
- json -- Templates for JSON file.
Make the vscp_class.h header file.
make_c_class_header.py >path/vscp_class.h
Make vscp_type.h header file.
make_c_type_header.py >path/vscp_ctype.h
Make the vscp_class.py header file.
make_python_class_header.py >path/vscp_class.py
Make vscp_type.py header file.
make_python_type_header.py >path/vscp_type.py
Make m_hashclass definitions for vscphelper.cpp.
make_vscphelper_hashclass.py >path/vscp_ctype.h
Make m_hashtype definitions for vscphelper.cpp.
make_vscphelper_hashtype.py path/vscp_hash_type.h
Generate sql for creation of sqlite db.
make_sqlite_db.py path/dbfile.sql
Generate sql for creation of mysql db.
make_mysql_db.py path/dbfile.sql
Make JSON/JSONP data. Use arg "jsonp" for JSONP.
make_json.py >path/events.json
or
make_json.py jsonp >path/events.jsonp
Make XML data.
make_xml.py >path/events.xml
Make sidebar content for specification document.
make_docs_sidebar.py >path/sidebar.md
Generate documentation for specification document.
make_docs.py -v -o <output-folder> -h
---------------------------------------------
-h/--help - This text.
-v/--verbose - Print output also to screen.
-o/--outdir - Folder to write output files to.
defaults to current folder.
Make class constants for the Javascript library.
make_js_class_constants.py >path/output
Make type constants for the Javascript library.
make_js_type_constants.py >path/output
Make class constants module for node.js.
make_nodejs_class_constants.py >path/output
Make type constants module for the node.js.
make_nodejs_type_constants.py >path/output
Convert XML file to JSON
_xmltojson.py ../classes/../classes/class_10_measurement.xml >outfile.json
- -v - Verbose
- -h - Help
In Python one can now use statements like the following to access information
# - Class token
print( o['class']['@token'])
# - All types
print( o['class']['type'])
# - Name for Type=6
print( o['class']['type'][6]
['@name'])
# - Unit = Degrees celsius
print( o['class']['type'][6]['units']['unit'][1])
# - # UTF8 symbol for degrees celsius
print( o['class']['type'][6]
['units']['unit'][1]['@symbol-utf8'])
# - Conversion formula to unit = 0
print( o['class']['type'][6]['units']['unit'][1]['@conversion'])for conversions a mustache template is used where {{val}} is the floating point value.
etc..
This is an internal bash script that is used on our internal development system to generate files for different projects and site.
dowork.sh <ftp-server> <user> <password>
It is possible to specify how user level software should render the data part of an event. It is possible to define many renderings but one is always available for VSCP Works. A typical event definition looks like this
<type id="51"
name="Request new security token"
token="VSCP_TYPE_CONTROL_REQUEST_SECURITY_TOKEN" >
<render>
<vscpworks
variables="
opt: function() { return e.vscpData[0]; },
zone: function() { return e.vscpData[1]; },
subzone: function() { return e.vscpData[2]; },
"
template="
{{lbl-start}}Opt : {{lbl-end}} {{val-start}}{{opt}}{{val-end}}{{newline}}
{{lbl-start}}Zone : {{lbl-end}} {{val-start}}{{zone}}{{val-end}}{{newline}}
{{lbl-start}}Subzone : {{lbl-end}} {{val-start}}{{subzone}}{{val-end}}{{newline}}
{{newline}}
"
/>
</render>
</type>The rendering for VSCP Works is defined here. Each rendering definition consist of two parts.
The first part is a variable substitution and define part that have access to the current event as the object e and therefore all it's data. As a variable also can be defined as a function you can assign values using functions which do calculations on the dynamic data that is provided by the environnement. A function here has access to standard Javascript functionality and the node-vscp package functionality or similar.
The second part is the actual rendering on mustache format. A defined variable should be written as {{variablename}} and will be substituted with the variable as of above.
There are some special substitution's available
variables and templates can have there definition strings prefixed with "BASE64:" to signal that they are encoded in BASE64. That is the example above will look like
<type id="51"
name="Request new security token"
token="VSCP_TYPE_CONTROL_REQUEST_SECURITY_TOKEN" >
<render>
<vscpworks
variables="BASE64:b3B0OiBmdW5jdGlvbigpIHsgcmV0dXJuIGUudnNjcERhdGFbMF07IH0sCiAgICAgICAgICAgICAgICB6b25lOiBmdW5jdGlvbigpIHsgcmV0dXJuIGUudnNjcERhdGFbMV07IH0sCiAgICAgICAgICAgICAgICBzdWJ6b25lOiBmdW5jdGlvbigpIHsgcmV0dXJuIGUudnNjcERhdGFbMl07IH0="
template="BASE64:e3tsYmwtc3RhcnR9fU9wdCA6IHt7bGJsLWVuZH19IHt7dmFsLXN0YXJ0fX17e29wdH19e3t2YWwtZW5kfX17e25ld2xpbmV9fSAgICAgICAgICAgICAgIAogICAgICAgICAgICAgICAge3tsYmwtc3RhcnR9fVpvbmUgOiB7e2xibC1lbmR9fSB7e3ZhbC1zdGFydH19e3t6b25lfX17e3ZhbC1lbmR9fXt7bmV3bGluZX19CiAgICAgICAgICAgICAgICB7e2xibC1zdGFydH19U3Viem9uZSA6IHt7bGJsLWVuZH19IHt7dmFsLXN0YXJ0fX17e3N1YnpvbmV9fXt7dmFsLWVuZH19e3tuZXdsaW5lfX0KICAgICAgICAgICAgICAgIHt7bmV3bGluZX19"
/>
</render>
</type>Base64 coded data may be simpler to handle and get things working for all codings (JSON, XML, SQL etc).
| Expression | Will be replaced with |
|---|---|
| {{lbl-start}} | Start of label (set to bold/color...) |
| {{lbl-end}} | End of label (Restet bold/color...) |
| {{val-start}} | Start of value (set to bold/color...) |
| {{val-end}} | End of value (Restet bold/color...) |
| {{newline}} | New line |
| {{ident}} | Default ident (what is default is defined by application) |
| {{unit}} | Unit as numerical (if defined) |
| {{unitstr}} | Unit name |
| {{unit_description}} | Unit description |
| {{unit_comment}} | Unit comment |
| {{unit_ascii}} | Unit in ASCII. Use if the environment cant handel Unicode. |
| {{unit_utf8}} | Unit in UTF8. Use in Unicode aware environments. |
This is another example of variable definitions
variables="
crc8: : function() { return e.vscpData[0]; }
time_epoch : function() { return e.vscpData[1]<<24 +
e.vscpData[2]<<16 +
e.vscpData[3]<<8 +
e.vscpData[4]] }
"and another
variables="
opt: function() { return e.vscpData[0]; },
zone: function() { return e.vscpData[1]; },
subzone: function() { return e.vscpData[2]; },
password: function() {
var rval = "";
for ( i=3;i<e.vscpData.length;i++) {
rval += String.fromCharCode(e.vscpData[i]);
}
return rval;
}
"Note that some characters has to be coded as they are reserved in XML. For completeness they are listed here
| Character | Encode as |
|---|---|
| < | < |
| > | > |
| & | & |
| " | " |
| ' | ' |
Technically variables are evaluated using the math.js package. The (mustache.js)[https://github.com/janl/mustache.js/] package is then used to obtain render information.