Eclipse.org Eclipse.org message Device Kit

XML Element 

<message> element

Device Kit Attributes Elements XML Reference
The message tag specifies the actual message or set of bytes that the are sent or received from the hardware device. The ascii, bytes, nibbles, string, utf8, tokens, parameter, parameters, and filter subtags define the content of a message. The specific tags to use within the message tag depend on a combination of the hardware specification and the controls that the application needs. For example, if the hardware communicates with bytes or eight bits use the bytes tag. If the hardware understands four-bit increments, use a series of nibbles to define the message. You can also set a filter mask for a message. The contents of the filter determine which bits are relevant. The content of a binary message is often defined by using the bytes subtag to specify a special byte or set of bytes. The content of a American National Standard Code for Information Interchange (ASCII) message is normally defined by using the ascii subtag. You can set the delimiter with the tokens tag. Messages can also have parameters that hold important value information. Specify message parameters with the parameter and parameters tags. Defining the messages correctly is very important activity. WARNING: Defining the messages incorrectly and sending the wrong messages to a hardware device can be dangerous.

Examples: message examples


NameTypeDescriptionUse
Element <message> attributes
idIDSpecifies an unique identifier for this element. After defining an element with the id attribute, other elements can reference this element by using the idref attribute. Since the id attribute value is used by the code generator to generate field and method names, no spaces, periods or commas should be used.optional
implementationNameSpecifies the implementation class name.optional
idrefIDREFSpecifies a reference to the element with the matching id attribute. The matching id attribute must be specified before the idref attribute can be used.optional

NameDescriptionUse
Element <message> elements
<description>Description of the message.0 to unbounded
<history>New Specifies the message history.0 to unbounded
<deprecated>Specifies that the contents of this element should be marked as deprecated.0 to 1
<specreference>Specification reference for this message.0 to unbounded
<ascii>Specifies a set of ASCII characters (8 bits) within the message.1 to unbounded
<bytes>Specifies a set of bytes. Each byte is 8 bits within the message.1 to unbounded
<nibbles>Specifies a set of nibbles. Each nibble is 4 bits within the message.1 to unbounded
<string>New Specifies a set of string characters within the message.1 to unbounded
<utf8>Specifies a set of UTF-8 characters within the message.1 to unbounded
<tokens>Specifies the message tokens.0 to 1
<parameters>Specifies a group of parameters.0 to unbounded
<filter>Specifies the message filter.0 to 1
<sentmessage>Specifies the message that was sent that caused this message.0 to 1

Sibling NameSibling Description
Element <message> element siblings
<method>Specifies the method to execute the command.
<data>Specifies the data to execute the command.
<dkml>Specifies the root element of a Device Kit &lt;b&gt;D&lt;/b&gt;evice &lt;b&gt;K&lt;/b&gt;it &lt;b&gt;L&lt;/b&gt;anguage (dkml) document.
<filter>
<stringmessage>New Defines a string message.
<utf8message>New Defines a utf8 string message.
<asciimessage>New Defines a ASCII string message.
<parameter>
<block>Defines a block. A block is similar to a parameter as it is defines an important part of the message but the value of the block is not reported external to the message when decoding the message. You can think of a block as an internal parameter needed to encode/decode a message. For example, a length block might be used to determine the length for a string in a message. The string parameter would be exposed to the user of the message but the length block would not be exposed since you can determine the length of the string based on the value of the string parameter.
<constantblock>Defines a constant block. A constant block is used to define part of the message that does not change.
<reserveblock>Defines a reserve block. A reserve block defines a part of the message that is reserved for future use.
<versionblock>Defines a version block. A version block defines a part of the message contains version information.
<idblock>Defines a id block. A id block defines a part of the message contains id information.
<identifierblock>Defines a identifierblock block. A identifier block defines a part of the message contains identifier information.
<typeblock>Defines a type block. A type block defines a part of the message contains type information.
<countblock>Defines a count block. A count block defines a part of the message contains count information. A count block can used to define the number of elements in a list parameter.
<lengthblock>Defines a length in bits block. The contents of the block is the length in bits. The value of the length block can be used to specify the length of a string or set of bits/bytes.
<sizeblock>Defines a length in bytes block. The contents of the block is the length in bytes (each byte is 8 bits). The value of the size block can be used to specify the size of a string or byte array
<segmentlengthblock>Defines a segment length in bits block. The segment length block defines the lengh in bits of the segment.
<segmentsizeblock>Defines a segment length in bytes block. The segment size block defines the lengh in bytes (each byte is 8 bits) of the segment.
<messagelengthblock>Defines a message length in bits block. The message length block defines the lengh in bits of the message.
<messagesizeblock>Defines a message length in bytes block. The message size block defines the lengh in bytes(each byte is 8 bits) of the message.
<bytesparameter>Defines a bytes parameter.
<bitsparameter>Defines a bits parameter.
<multiparameter>Defines a multiple parameter.
<variablelengthparameter>Defines a variable length parameter. Normally, a lengthblock or sizeblock should be defined to specify the size of the variable length parameter.
<listparameter>Defines a list parameter. Normally, a countblock would be needed to specify the number of items in the list.
<mapparameter>Defines a map parameter.
<arrayparameter>Defines a array parameter.
<utf8stringparameter>Defines a UTF-8 string parameter.
<stringparameter>Defines a string parameter.
<booleanparameter>Defines a binary boolean parameter. Normally, a boolean parameter length should not be longer than 1 bit.
<numberparameter>
<integerparameter>Defines a binary integer parameter. An integer parameter length should not be longer than 32 bits (4 bytes).
<unsignedintegerparameter>Defines a binary unsigned integer parameter. An unsigned integer parameter length should not be longer than 32 bits (4 bytes).
<longparameter>Defines a binary long parameter. An long parameter length should not be longer than 64 bits (8 bytes).
<unsignedlongparameter>Defines a binary unsigned long parameter. An unsigned long parameter length should not be longer than 64 bits (8 bytes).
<shortparameter>Defines a binary short parameter. An short parameter length should not be longer than 16 bits (2 bytes).
<unsignedshortparameter>Defines a binary unsigned short parameter. An unsigned short parameter length should not be longer than 16 bits (2 bytes).
<byteparameter>Defines a binary byte parameter. An byte parameter length should not be longer than 8 bits (1 byte).
<unsignedbyteparameter>Defines a binary unsigned byte parameter. An unsigned byte parameter length should not be longer than 8 bits (1 byte).
<floatparameter>Defines a binary IEEE 754 floating-point single 32 bit parameter. The float parameter length should be 32 bits (4 bytes).
<doubleparameter>Defines a binary IEEE 754 floating-point double 64 bit parameter. The double parameter length should be 64 bits (8 bytes).
<segment>
<parametersegment>
<singleparametersegment>
<choicesegment>
<protocol>
<transport>
<transporttest>
<receiver>Defines a receiver transport.
<value>
<description>Specifies the messages description.
<history>New Specifies the messages history.
<deprecated>Specifies that the contents of this element should be marked as deprecated.
<specreference>Specification reference for this group of messages.
<key>Specifies the unique messages key.

Element NameElement Description
Element <message> element tree
<dkml>Specifies the root element of a Device Kit &lt;b&gt;D&lt;/b&gt;evice &lt;b&gt;K&lt;/b&gt;it &lt;b&gt;L&lt;/b&gt;anguage (dkml) document.
¦-<adapter>Specifies an adapter.
¦ ¦-<command>Defines a command supported by this concrete device.
¦ ¦ ¦-<message>Specifies the message to execute the command.
¦ ¦ ¦ ¦-<description>Description of the message.
¦ ¦ ¦ ¦-<history>New Specifies the message history.
¦ ¦ ¦ ¦ ¦-<description>Description of the history.(see description)
¦ ¦ ¦ ¦ ¦-<provider>Specifies the provider history.
¦ ¦ ¦ ¦ ¦-<version>Version of the history documentation.
¦ ¦ ¦ ¦-<deprecated>Specifies that the contents of this element should be marked as deprecated.
¦ ¦ ¦ ¦-<specreference>Specification reference for this message.
¦ ¦ ¦ ¦ ¦-<description>Description of the specification reference.(see description)
¦ ¦ ¦ ¦ ¦-<deprecated>Specifies that the contents of this element should be marked as deprecated.(see deprecated)
¦ ¦ ¦ ¦ ¦-<spec>The protocol specification documentation.
¦ ¦ ¦ ¦ ¦ ¦-<description>Description of the specification.(see description)
¦ ¦ ¦ ¦ ¦ ¦-<history>New Specifies the specification history.(see history)
¦ ¦ ¦ ¦ ¦ ¦-<deprecated>Specifies that the contents of this element should be marked as deprecated.(see deprecated)
¦ ¦ ¦ ¦ ¦ ¦-<speccomment>Comment about the protocol specification documentation.
¦ ¦ ¦ ¦ ¦ ¦-<specdate>Date of the protocol specification documentation.
¦ ¦ ¦ ¦ ¦ ¦-<spectitle>Title of the protoocol specification documentation.
¦ ¦ ¦ ¦ ¦ ¦-<specurl>Url of the protocol specification documentation.
¦ ¦ ¦ ¦ ¦ ¦-<specvendor>Vendor of the protocol specification documentation.
¦ ¦ ¦ ¦ ¦ ¦-<specversion>Version of the protocol specification documentation.
¦ ¦ ¦ ¦ ¦-<specsection>The reference to section in the protocol specification documentation.
¦ ¦ ¦ ¦-<ascii>Specifies a set of ASCII characters (8 bits) within the message.
¦ ¦ ¦ ¦-<bytes>Specifies a set of bytes. Each byte is 8 bits within the message.
¦ ¦ ¦ ¦-<nibbles>Specifies a set of nibbles. Each nibble is 4 bits within the message.
¦ ¦ ¦ ¦-<string>New Specifies a set of string characters within the message.
¦ ¦ ¦ ¦ ¦-<encoding>New Specifies string encoding.
¦ ¦ ¦ ¦-<utf8>Specifies a set of UTF-8 characters within the message.
¦ ¦ ¦ ¦-<tokens>Specifies the message tokens.
¦ ¦ ¦ ¦-<parameters>Specifies a group of parameters.
¦ ¦ ¦ ¦ ¦-<description>Specifies the parameters description.(see description)
¦ ¦ ¦ ¦ ¦-<history>New Specifies the parameters history.(see history)
¦ ¦ ¦ ¦ ¦-<units>Specifies the parameters units.
¦ ¦ ¦ ¦ ¦ ¦-<description>Description of the units.(see description)
¦ ¦ ¦ ¦ ¦ ¦-<history>New Specifies the units history.(see history)
¦ ¦ ¦ ¦ ¦ ¦-<deprecated>Specifies that the contents of this element should be marked as deprecated.(see deprecated)
¦ ¦ ¦ ¦ ¦ ¦-<specreference>Specification reference for this units.(see specreference)
¦ ¦ ¦ ¦ ¦-<deprecated>Specifies that the contents of this element should be marked as deprecated.(see deprecated)
¦ ¦ ¦ ¦ ¦-<specreference>Specification reference for this group of parameters.(see specreference)
¦ ¦ ¦ ¦ ¦-<key>Specifies the unique parameters key.
¦ ¦ ¦ ¦ ¦-<parameters>Specifies the parameters.(see parameters)
¦ ¦ ¦ ¦-<filter>Specifies the message filter.
¦ ¦ ¦ ¦ ¦-<description>Description of the filter.(see description)
¦ ¦ ¦ ¦ ¦-<history>New Specifies the filter history.(see history)
¦ ¦ ¦ ¦ ¦-<deprecated>Specifies that the contents of this element should be marked as deprecated.(see deprecated)
¦ ¦ ¦ ¦ ¦-<specreference>Specification reference for this filter.(see specreference)
¦ ¦ ¦ ¦ ¦-<bytes>Specifies the message filter (Bit off - ignore, Bit on - compare).(see bytes)
¦ ¦ ¦ ¦-<sentmessage>Specifies the message that was sent that caused this message.
¦ ¦-<commands>Specifies a command group.
¦ ¦ ¦-<command>Specifies the command within the group of commands.(see command)
¦ ¦-<group>Defines a group supported by this concrete device.
¦ ¦ ¦-<command>Specifies a command that is supported by this group.(see command)
¦ ¦ ¦-<commands>Specifies a command group.(see commands)
¦ ¦ ¦-<group>Specifies a group.(see group)
¦ ¦ ¦-<measurement>Specifies a measurement supported by this group.
¦ ¦ ¦ ¦-<message>Specifies the measurement message.(see message)
¦ ¦ ¦ ¦-<readcommand>Specifies the command to request a read of the current value of the measurement.
¦ ¦ ¦ ¦ ¦-<message>Specifies the message to execute the command.(see message)
¦ ¦ ¦ ¦-<writecommand>Specifies the command to request a change of the measurement value.
¦ ¦ ¦ ¦ ¦-<message>Specifies the message to execute the command.(see message)
¦ ¦ ¦ ¦-<signal>Specifies the signal containing the measurement value.
¦ ¦ ¦ ¦ ¦-<message>Specifies the message to trigger the signal.(see message)
¦ ¦ ¦ ¦ ¦-<signal>Specifies the signal to listen. (see signal)
¦ ¦ ¦ ¦ ¦-<messages>Specifies the messages to trigger the signal.
¦ ¦ ¦ ¦ ¦ ¦-<message>Specifies the message.(see message)
¦ ¦ ¦-<signal>Specifies a signal supported by this group.(see signal)
¦ ¦-<measurement>Defines a measurement supported by this concrete device.(see measurement)
¦ ¦-<signal>Defines a signal supported by this concrete device.(see signal)
¦ ¦-<device>Specifies the device used by the adapter.
¦ ¦ ¦-<command>Specifies a command that is supported by this device.(see command)
¦ ¦ ¦-<commands>Specifies a command group.(see commands)
¦ ¦ ¦-<group>Defines a group supported by this device.(see group)
¦ ¦ ¦-<measurement>Specifies a measurement supported by this device.(see measurement)
¦ ¦ ¦-<signal>Specifies a signal supported by this device.(see signal)
¦ ¦ ¦-<transport>Specifies the transport used by the device.
¦ ¦ ¦ ¦-<message>Specifies a transport message.(see message)
¦-<adaptertest>Specifies an adapter test.
¦ ¦-<send>Specifies the message(s) to send during the test.
¦ ¦ ¦-<message>Specifies the message to send.(see message)
¦ ¦-<adapter>Specifies the adapter to be tested.(see adapter)
¦-<agent>Specifies an agent.
¦ ¦-<agentmodel>Specifies the agent model used by the agent.
¦ ¦ ¦-<device>Specifies the device used by the agent model.(see device)
¦ ¦-<device>Specifies the device used by the agent.(see device)
¦ ¦-<command>Specifies a command that is supported by this device.(see command)
¦ ¦-<commands>Specifies a command group.(see commands)
¦ ¦-<group>Defines a group supported by this device.(see group)
¦ ¦-<measurement>Specifies a measurement supported by this device.(see measurement)
¦ ¦-<signal>Specifies a signal supported by this device.(see signal)
¦-<agentmodel>Specifies the agent model used by the agent.(see agentmodel)
¦-<agenttest>Specifies an agent test.
¦ ¦-<send>Specifies the message(s) to send during the test.(see send)
¦ ¦-<agent>Specifies the agent to be tested.(see agent)
¦ ¦-<agentmodeltest>Specifies the agent model test.
¦ ¦ ¦-<agentmodel>Specifies the agent model to be tested.(see agentmodel)
¦-<agentmodeltest>Specifies an agent model test.(see agentmodeltest)
¦-<concrete>Specifies a concrete device.
¦ ¦-<command>Defines a command supported by this concrete device.(see command)
¦ ¦-<commands>Specifies a command group.(see commands)
¦ ¦-<group>Defines a group supported by this concrete device.(see group)
¦ ¦-<measurement>Defines a measurement supported by this concrete device.(see measurement)
¦ ¦-<signal>Defines a signal supported by this concrete device.(see signal)
¦ ¦-<transport>Specifies the transport used by the concrete device.(see transport)
¦-<concretetest>Specifies a concrete test.
¦ ¦-<concrete>Specifies the concrete device to be tested.(see concrete)
¦-<connectiontest>Specifies an connection test.
¦ ¦-<send>Specifies the message(s) to send during the test.(see send)
¦-<device>Specifies a device.(see device)
¦-<devicetest>Specifies a device test.
¦ ¦-<device>Specifies the device to be tested.(see device)
¦-<profile>Specifies a profile.
¦ ¦-<command>Specifies a command that is supported by this profile.(see command)
¦ ¦-<commands>Specifies a command group.(see commands)
¦ ¦-<group>Defines a group supported by this profile.(see group)
¦ ¦-<measurement>Specifies a measurement supported by this profile.(see measurement)
¦ ¦-<signal>Specifies a signal supported by this profile.(see signal)
¦ ¦-<adapter>Specifies the adapter used by the profile.(see adapter)
¦ ¦-<device>Specifies the device used by the profile.(see device)
¦-<profiletest>Specifies a profile test.
¦ ¦-<send>Specifies the message(s) to send during the test.(see send)
¦ ¦-<profile>Specifies the profile to be tested.(see profile)
¦-<testagent>Specifies a test agent.
¦ ¦-<profile>Specifies the profile to be tested.(see profile)
¦-<receivertest>Specifies a receiver transport test.
¦ ¦-<send>Specifies the message(s) to send during the test.(see send)
¦-<transport>Specifies a transport.(see transport)
¦-<transporttest>Specifies a transport test.
¦ ¦-<send>Specifies the message(s) to send during the test.(see send)
¦ ¦-<transport>Specifies the transport to be tested.(see transport)

Copyright (c) 2009 IBM. See license in Legal section. 2009-01-22 Device Kit XML Reference 1.2.0