Mail Embedded VSCP

Back to VSCP Proposals

This is a format that can be used to embed VSCP events in a mail message, web-page, SMS, MMS and other types of message structures. The format can be used to send events between machines or by users.

There are two formats. XML and Token format. The XML format is best for when computers construct the message and Token based format is best when humans construct the message.

XML - General Format

<?xml version = "1.0" encoding = "UTF-8" ?>
<!-- Version 0.0.1    2005-08-09 -->
   <user>optional username</user>
   <password>optional password</password>
   <!-- Can contain one or many -->
       <class>0-65535</class> <!-- If higher the 511 its a Level II event -->
       <type>0-65535 (0-255 for Level I)</type>
       <priority>0-7</priority> <!-- Priority 0 is highest -->
       <hardcoded>0|1</hardcoded> <!-- 1 if address is hardcoded -->
       <!-- If GUID is left out the interface GUID is used -->
       <guid>GUID as a hex number with MSB first</guid>
       <obid>interface id</obid>
       <timestamp>Relative time stamp in uS</timestamp>
       <!-- One or several -->
       <data>Data as up to 32 comma separated hex(0x) or decimal values</data>
       <!-- or -->
       <verbatim>Clear text</verbatim>
<!-- Standard CAN frame -->
<can extended="1" rtr="0">
   <id>CAN id</id>
   <data>Data as up to 8 comma separated hex(0x) or decimal values</data>
   <timestamp>Relative time stamp in uS</timestamp>

Verbatim content is translated into UTF-8 character data. <data> and <verbatim> tags can be mixed and be repeated and the data buffer is filled with data in the order data is received.


<?xml version = "1.0" encoding = "UTF-8" ?>


<?xml version = "1.0" encoding = "UTF-8" ?>

Where a switch %true which expands to 0x01 has been used.

The XML data can be embedded once or many time in a mail or SMS message.

Predefined event definitions

To simplify the event generation events or a number of events with the above format can be stored on the server and a message sent with event-name will trigger the event or the event sequence. One or several triggers can be present in a message.

  • A predefined event definition can also be activated when a mail is received from a certain sender, a SMS, MMS from a certain phone etc.

Thats is an email/SMS message with “all_lamps_on” can actually turn on all lamps in the house. Generating the correct VSCP events.


A list with allowed events can be used to define events that can be sent by this way to secure the system from “dangerous events” being sent.

The <user> and <password> tag can be used to extend the security further.

Token - General Format

The token based format is perfect when humans want to issue VSCP events. Typical example is

kitchen_lamp on

which is translated to

CLASS1.CONTROL  Type=5 TurnOn where "kitchen_lamp" defines zone/subzone

The general style is thus that the first token defines the zone/subzone and the second and further tokens on a line define the event and the data bytes for the event. In the above sample token on and off will generate the CLASS1:CONTROL TurnOn and TurnOff events respectively.

All meanings for tokens are user defined and find in a table. This table also defines how many tokens that should be expected on a row to define a valid event.

Another example can be to read a register

x readreg 10 0x22

Read register 34 for node 10. The x is just a placeholder for the zone/subzone pair and may actually have any value. The token readreg defines that two extra tokens must follow and where there data goes but in this case also tells that an answer should be sent to the sender of the message. Typically this answer is in human readable form.

It is also possible to create tokens that generate one specific event or even a bunch of them Imagine we want to start five motors in different locations but which are not zoned together

x start

can do that for us. Sending

CLASS1.CONTROL  Type=5 TurnOn to zone=z1 subzone=s1
CLASS1.CONTROL  Type=5 TurnOn to zone=z2 subzone=s2
CLASS1.CONTROL  Type=5 TurnOn to zone=z3 subzone=s3
CLASS1.CONTROL  Type=5 TurnOn to zone=z4 subzone=s4
CLASS1.CONTROL  Type=5 TurnOn to zone=z5 subzone=s5  

in turn. In an answer is wanted it can be generated and the outcome of the event being checked as well.

rfc/mail_embedded_vscp.txt · Last modified: 2018/02/08 17:47 (external edit)
[unknown button type]
Except where otherwise noted, content on this wiki is licensed under the following license: Public Domain
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki