Defining new serial protocol (or editing existing one)
Five data type categories that will compose a whole serial protocol.
[FL] Flag : Constant value of 'Byte' (1
byte) or 'Text' (byte array). The value and length of this field are known
through the communication. The value of this field will be checked through the
serial communication and must be the same with the defined value. The length of
this field is 1 byte in 'Byte' type and array of several bytes in 'Text' type.
The text will be encoded as 1byte or 2byte-characters.
[VA] Variable size data : The value and
length of this field are not known through the communication. The value of
this field will be mapped to a Serial Label (or
from a Serial Text Field) in an applet or
application.
[FX] Fixed size data : The value of this
field is not known but the length of this field is known through the
communication. The value of this field will be mapped to (or from) a component
in an applet or application.
[DE] Delimiter : Constant value of byte (1
byte). The value and length of this field are known through the communication.
Every value of this field is to be the same through this protocol. If you
change the value of one of delimiters contained in a protocol, the values of
rest delimiters will be changed automatically to be same with the changed one.
Like a Flag, the value of this field will be checked through the serial
communication and must be the same with the defined value. The length of this
field is 1 byte
[CS] Check sum : The length of this field
is 1 byte and the value of this field is dependent on the value of other
fields. Every field has its own check sum property. You can choose several
fields that will compose this check sum value. The value of this field is an
"exclusive or (XOR)" of selected fields.
[FL] and [DE] will do the same work through send or receive protocol. However,
[VA] and [FX] work differently by whether is it for sending or not (receiving).
Both of [VA] and [FX] contain some meaningful data which is mapped to (or from)
a single visual component or several visual components of applet or
application.
In sending, [VA] and [FX] will read texts or values from components and compose
a serial data along with other [FL] or [DE]s and the composed serial data will
be sent to the target device.
In receiving, a received serial data will be parsed and resolved. The texts or
values that are resolved by pre-defined receive serial protocol will be
displayed by visual components of applet or application.
One thing that you may be still curious about is that 'How to point out the
start and the end of [VA]? (How to know the length of [VA]?)'. Read the rest of
this page.
Before we go further, please be noted that there are 6 properties per each of data
field.
Category : the category of this data field. FL, VA, FX, DE, CS.
Check Sum. : whether the value of this data field is included in Check
sum data field or not.
Symbol : the symbol of this data field. [FL] : f0, f1,... [VA] : v0,
v1,... [FX] : x0, x1,... [DE] : de, [CS] : cs. The suffix numbers will be generated
automatically by the program.
Type : the type of this data. Byte, Byte array, Short, Integer, Float,
Double, Text and Bit(byte).
Length : the length of this data in byte.
Value : the value of this data.
Note : notes for this data.
Send protocol
[FL]
Flag has two types
Byte : single byte data, the length is 1 and the value must be a constant
Hex value prefixed by '0x'.
You may use commonly used ASCII Control characters
like 'STX'
or 'ETX' as its value.
Text : Accept any ASCII Control characters value and translate it into a byte array.
The length of this data is the size of translated byte array. Two byte
characters such as Korean or Chinese also can be used. The length will be
assigned automatically by selecting type or giving value.
f0 is '02' and f1 is '1B' in Hex.
f2 is '43,4F,4D,4D,41,4E,44,30,31' and f3 is 'C7,D1,B1,DB,' in Hex.
[VA]
Variable size data has only one type in sending case.
Byte array : an array of byte data which is generated from a text data.
The text data will be read from a specified visual component (Serial
Text Field) in an applet or application right before composing a complete
serial protocol and sending it. By changing the text of the component before
sending a serial data, you can change this value.
The length of this data is dependent on the text typed in Serial Text
Field component.
v0 is a byte array value which is read from a component that has 'v0' as its 'Write destination' property.
[FX]
Fixed size data has two types in sending case
Byte : single 'Byte' (unsigned) data, the length is 1 and the value will be read from
a specified visual component (switch) in an applet or application right before
composing a complete serial protocol and sending it. By changing the location of
switch knob or the value in SerialTextField before sending a serial data, you can change this value.
This value ranges from 0 to 255.
Short : single 'Short' (unsigned) data, the length is 2. This value
ranges from 0 to 65535. Other than these, same with 'Byte' type. Please refer to
the tutorial sample page for details.
Integer : single 'Integer' (signed) data, the length is 4. This value
ranges from -2147483648 to 2147483647. Other than these, same with 'Byte' type.
Please refer to the tutorial sample page for details.
Float : single 'Float' (IEEE 754 single precision floating point) data, the length is
4. Other than these, same with 'Byte' type. Please refer to the tutorial sample
page for details.
[ IEEE 754 4-byte single precision
floating point specification ]
Say byte representation (4 bytes) is
: bits
If the bits is 0x7f800000, it is
positive infinity.
If the bits is 0xff800000, it is
negative infinity.
If the bits is any value in the range
0x7f800001 through 0x7fffffff or in the range
0xff800001 through 0xffffffff, it is
NaN
In all other cases, let s , e
, and m be three integer values that can be computed from
the
byte representation bits :
If (bits >> 31) is 0, s
is 1. Else s is -1.
e is ((bits >> 23)
& 0xff).
If e is 0, m
is (bits & 0x7fffff) << 1. Else m is (bits &
0x7fffff) | 0x800000.
Then the floating-point result equals
the value of the mathematical expression s*m*2 (e-150)
Double : single 'Double' (IEEE 754 double precision floating point) data, the length is
8. Other than these, same with 'Byte' type. Please refer to the tutorial sample
page for details.
[ IEEE 754 8-byte double precision
floating point specification ]
Say byte representation (8 bytes) is
: bits
If the bits is 0x7ff0000000000000L,
it is positive infinity.
If the bits is 0xfff0000000000000L,
it is negative infinity.
If the bits is any value in the range
0x7ff0000000000001L through 0x7fffffffffffffffL
or in the range 0xfff0000000000001L
through 0xffffffffffffffffL, it is NaN
In all other cases, let s , e
, and m be three integer values that can be computed from
the
byte representation bits :
If (bits >> 63) is 0, s
is 1. Else s is -1.
e is ((bits >> 52)
& 0x7ffL).
If e is 0, m
is (bits & 0xfffffffffffffL) << 1. Else m is (bits &
0xfffffffffffffL) | 10000000000000L.
Then the floating-point result equals
the value of the mathematical expression s*m*2 (e-1075)
Byte array : set of bytes each of that are same with single byte data
above. You must specify the length (size) of byte array.
Bit (byte) : single byte data, the length is 1 and you can set the write
destination of each bits separately in bit-level.
The Please refer to the tutorial sample page for details.
x0 is a byte value which is read from a component that has 'm0' as its 'Write
destination' property.
x5 is a set of 3 bytes. Each of values is read from components that have
'm5','m6' and 'm7' as each of its 'Write destination' property in order. If the
value of x6 (Bit) is 'null', this protocol will fail in protocol verification.
[DE]
Delimiter has only one type.
Byte : single byte data., the length is 1 and the value must be a
constant Hex value prefixed by '0x'.
You may use commonly used ASCII Control characters
like 'STX'
or 'ETX' as its value.
Every de has the same value 'AD' in Hex.
[CS]
Please refer to the end of this section.
Example of composing a serial protocol (send)
Ex. 1. When the serial protocol definition is as following table, (Constant
byte value STX(0x02), three byte values data#s and each value of data#s
will be read from a switch category component and is separated by a comma (,).
Constant byte value ETX(0x03) finally)
| Value |
STX |
data1 |
comma
(,) |
data2 |
comma
(,) |
data3 |
ETX |
| Size
(byte) |
1 |
1 |
1 |
1 |
1 |
1 |
1 |
| Note |
same
with 0x02 |
read
from a switch |
delimiter |
read
from a switch |
delimiter |
read
from a switch |
same
with 0x03 |
Then the serial protocol edit in HelloDevice IDE is
.
If the value of switch (with write destination 'm0') is 20 (0x14), the value
of switch (with write destination 'm1') is 40 (0x28) and the value of switch
(with write destination 'm2') is 60 (0x3C),
then the send data will be
02,14,2C,28,2C,3C,03
in Hexadecimal.
Ex. 2. When the serial protocol definition is as following table,
(Constant byte value 0x02, a byte data 'data1' which's value will be read from a switch
category component and a variable size text data 'text data1' which's value will be read from
a Serial Text Field. Constant byte value 0x03 finally)
| Value |
0x02 |
data1 |
text
data1 |
0x03 |
| Size
(byte) |
1 |
1 |
unknown |
1 |
| Note |
same
with "STX" |
read
from a switch |
length-unknown
text |
same
with "ETX" |
Then the serial protocol edit in HelloDevice IDE is
.
If the value of switch (with write destination 'm0') is 30 (0x1E) and the text
of Serial Text Field (with text input, write destination 'v0') is 'HelloDevice IDE'
(48,65,6C,6C,6F,44,65,76,69,63,65,,20,49,44,45),
then the send data will be
02,1E,48,65,6C,6C,6F,44,65,76,69,63,65,,20,49,44,45,03
in Hexadecimal.
Ex. 3. When the serial protocol definition is as following table,
(Constant text 'SETVALUE' and two variable size text data (text data1, text
data2). Each of text data will be read from a Serial Text Field. The two text data
is separated by a comma (,). Constant byte value 0xFF finally)
| Value |
constant
text |
text
data1 |
comma(,) |
text
data2 |
0xFF |
| Size
(byte) |
8 |
unknown |
1 |
unknown |
1 |
| Note |
length-known
text |
length-unknown
text |
delimiter |
length-unknown
text |
flag |
Then the serial protocol edit in HelloDevice IDE is
.
If the text of Serial Text Field (with write destination 'v0') is 'VOLT'
(56,4F,4C,54) and the text of Serial Text Field (with text input, write destination 'v1')
is '13.5000' (31,33,2E,35,30,30,30),
then the send data will be
53,45,54,56,41,4C,55,45,56,4F,4C,54,2C,31,33,2E,35,30,30,30,FF
in Hexadecimal.
Refer to tutorial samples page for more
concrete example of defining and editing serial protocols.
Receive protocol
[FL]
Same as send protocol
[VA]
Variable size data has only one type in receiving case.
Byte array : an array of byte data which will be parsed to a text right
after receiving a serial data. The parsed text will be written to a specified
visual component (Serial Label) in an applet
or application. The value of this field has the form v<address>. Once a byte array
is received, the byte array will be translated to a text and will be written to a
component(Serial Label) that has 'v0' as its 'Value expression' property.
When it represents a value in ASCII code like 1234.5678 (31,32,33,34,2E,35,36,37,38
in Hex), this can be mapped to other gauge components (not Serial Label) by
setting its Value = m<address>.
Note that the length of this data is notified by several kinds of symbols
specified in the 'length' property. - f0, de, xo, end or similar.
Following cases show that several symbols.
- The end of this [VA] is identified by the [FL] which's value is 0x33 in Hex.
- End-specifying field 'f0' must be placed right behind the corresponding [VA].
- Note that this [VA] should not contain byte data '0x33' in Hex. to prevent the
possibility of confusion.
- The end of this [VA] is identified by the [DE] which's value is 0x2C in Hex.
- End-specifying field 'de' must be placed right behind the corresponding [VA].
- Note that this [VA] should not contain byte data '0x2C' in Hex. to prevent the
possibility of confusion.
- the length of this [VA] is specified by the preceding [FX] (x0). The length is
the byte value of the 'x0''s second component which is identified by the symbol
'va' in this case.
- Length-specifying field 'x0' must be placed prior to the corresponding [VA].
- The end of this [VA] is identified by the 'end' symbol. This means the
protocol ends with this field. When an applet or application receives a data, it
will take the whole bytes from the start of this field to end of the received
data as 'v0'.
- Note that this [VA] should be placed at the end of the protocol in this case.
The value of this field can be 'null' so that no visual components will render its
context.
[FX]
Fixed size data has three types in receiving case
Byte : single 'Byte' (signed) data, the length is 1 and the value will be written to
a specified visual component (gauge) in an applet or application and displayed
by them right after receiving a serial data.
If the value of this field is 'null', no visual components will display this
received value.
If the value of this field is 'va', the received value is specifying a length of
a [VA] field which will come after this field. The [VA] field must specify its length property with the symbol of this [FX] field.
This value ranges from 0 to 255.
Short : single 'Short' (unsigned) data, the length is 2. This value
ranges from 0 to 65535. Other than these, same with 'Byte' type. Please refer to
the tutorial sample page for details.
Integer : single 'Integer' (signed) data, the length is 4. This value
ranges from -2147483648 to 2147483647. Other than these, same with 'Byte' type.
Please refer to the tutorial sample page for details.
Float : single 'Float' (IEEE 754 single precision floating point) data, the length is
4. Other than these, same with 'Byte' type. Please refer to the tutorial sample
page for details and please refer to 'Send protocol' section for IEEE 754 4-byte
single precision floating point specification.
Double : single 'Double' (IEEE 754 double precision floating point) data, the length is
8. Other than these, same with 'Byte' type. Please refer to the tutorial sample
page for details and please refer to 'Send protocol' section for IEEE 754 8-byte
double precision floating point specification.
Byte array : set of bytes each of that are same with single byte data
above. You must specify the length (size) of byte array.
Text : Accepts byte array with a specified length and the byte
array will be parsed to a text right after receiving a serial data. The parsed
text will be written to a specified visual component (Serial
Label) in an applet or application.
Bit (byte) : single byte data, the length is 1 and you can set the write
destination of each bits separately in bit-level.
The Please refer to the tutorial sample page for details.
x0 is a byte value which's value will be written to and displayed by a visual
component that has 'm0' as its 'Value expression' property.
x1 is a 2-byte short value which's value will not be written to and displayed by any
visual component.
x2 is a 4-byte integer value which's value will be regarded as a length of a [VA] field
which comes after this field.
x3 is a 4-byte float value which's value will be written to and displayed by a visual
component that has 'm1' as its 'Value expression' property.
x4 is a 8-byte double value which's value will be written to and displayed by a visual
component that has 'm2' as its 'Value expression' property.
x5 is a byte array each of bytes will be resolved and processed as is
respectively.
x6 is a byte array with length 6 which will be translated into a text and the
text will be written to a
SerialLabel that has 'v0' as its 'Value expression' property.
x7 is a byte array with length 5 which will be translated into a text and the
text should represents a value in ASCII form (ex 33,31,2E,34,48 represents
31.48). The value will be written to and displayed by a visual
component that has 'm5' as its 'Value expression' property.
x8 is a byte array with length 3 which will be translated into a text but the text will not be
written to any Serial Label.
[DE]
Same as send protocol
[CS]
Please refer to the end of this section.
Example of composing a serial protocol
(receive)
Ex. 1. When the serial protocol which is supposed to be received is as
following table, (Constant byte value 0x02, three fixed size byte value each
of which will
be displayed by a gauge category component except the second one. Each of
three fixed size byte value is unknown and is separated by a comma (,) and a
constant byte value 0x03 finally.)
| Value |
0x02 |
data1 |
comma(,) |
data2 |
comma(,) |
data3 |
0x03 |
| Size
(byte) |
1 |
1 |
1 |
1 |
1 |
1 |
1 |
| Note |
same
with "STX" |
displayed
by a gauge |
delimiter |
not
to be displayed |
delimiter |
displayed
by a gauge |
same
with "ETX" |
Then the serial protocol edit in HelloDevice IDE is
.
If a received data is
02,14,2C,28,2C,3C,03
in Hexadecimal, then the gauge (with value expression 'm0') will indicate 20
(0x14), the gauge (with value expression 'm1') will indicate 60 (0x3C).
Ex. 2. When the serial protocol which is supposed to be received is as
following table, (Constant byte value 'STX' (0x02), two variable size text
data which will
be displayed by a Serial Label component except the second one. The length and
context of the two text data are not known. The end of the first text is
denoted by a comma (,) and the end of the second text is denoted by a
constant byte value 'ETX' (0x03).)
| Value |
STX |
text data1 |
comma(,) |
text data2 |
ETX |
| Size
(byte) |
1 |
unknown |
1 |
unknown |
1 |
| Note |
same with 0x02 |
displayed by a Serial Label |
delimiter |
not to be
displayed |
same with 0x03 |
Then the serial protocol edit in HelloDevice IDE is
.
If a received data is
02,31,33,2E,30,30,2C,56,61,6C,75,65,31,20,69,73,03
in Hexadecimal, then the Serial Label (with value expression 'v0') will
display '13.00', and the second text 'Value is' will not displayed at all.
Ex. 3. When the serial protocol which is supposed to be received is as
following table, (Constant byte value 0x02, a fixed size data with length 3,
two variable size text data that will
be displayed by Serial Label components. The length and context of the two
text data are unknown. The length of the first text is contained in the
preceding fixed size data and the end of the second text is denoted by a
constant byte value 0x03. The fixed size data is totally 3 bytes. The first
byte value will be displayed by a gauge category component , the second byte
value means the length of text data1 and the third byte value will be
dismissed.)
| Value |
0x02 |
fixed size data |
text data1 |
text data1 |
0x03 |
| Size
(byte) |
1 |
3 |
unknown |
unknown |
1 |
| Note |
same
with "STX" |
contains the length of text
data1 |
displayed by a Serial Label |
displayed by a Serial Label |
same
with "ETX" |
Then the serial protocol edit in HelloDevice IDE is
.
And this serial protocol edit is same with
.
The fixed size data with length of 3 can be rewritten separately like above.
If a received data is
02,14,0B,28,48,65,6C,6C,6F,44,65,76,69,63,65,49,44,45,03
in Hexadecimal, then the gauge (with value expression 'm0') will indicate 20
(0x14), the Serial Label (with value expression 'v0') will display
'HelloDevice'. The length of this text data is 11(0x0B). The Serial Label (with value expression
'v1') will display 'IDE'. The third byte value of a fixed size data (0x28)
will not be displayed at all.
Ex. 4. When the serial protocol which is supposed to be received is as
following table, (A fixed size text data with length 5, and a variable size
text data. Both of text data will
be displayed by Serial Label components. The length of the first fixed size
text data is known but the context is not known. The end of the second text
data is the end of the submitted serial data.)
| Value |
fixed size text data |
text data |
| Size (byte) |
5 |
unknown |
| Note |
but contents unknown,
displayed by a Serial Label |
displayed by a Serial Label |
Then the serial protocol edit in HelloDevice IDE is
.
If a received data is
48,65,6C,6C,6F,53,45,4E,41,20,54,65,63,68,6E,6F,6C,6F,67,69,65,73
in Hexadecimal, then the Serial Label (with value expression 'v0') will
display 'Hello'. The length of this text data is 5 (fixed). The Serial Label (with value expression
'v1') will display 'SENA Technologies'.
Refer to tutorial samples page for more
concrete example of defining and editing serial protocols.
Acknowledge (ACK), Negative Acknowledge (NAK) and Timeout :Receive protocols
only
By setting this property of receive protocol, you can send additional data
to the connected device right after receiving a data.
According to the received data, you can send two types of data. The one is ACK
which will be sent when the received data is perfect and meets the receive
protocol specification and the other is NAK which will be sent when the received
data is blank, corrupted or does not meet the receive protocol specification.
Uncheck these fields if you do not want to send any data in response to
the received data. Certainly, you can send one of these data selectively.
Read more about the mechanism of serial communication
You can specify a Acknowledge : ACK (or Negative Acknowledge : NAK) value in various form.
ex)
- Direct description :
0x00 (single byte value
in Hex.)
ESC (single byte value
in an ASCII Control characters)
0x00,ESC (in series of
single byte value and an ASCII Control characters
separated by a comma.)
0x00,0x02,0x03 (in
series separated by a comma.)
- Specifying a send protocol :
s1
(specifying an already existing send protocol)
Check sum
The exclusive or (XOR) of every value of chosen fields replaces the value of
Check sum field. There should be only one [CS] in a single protocol.
ex) sending
Two fields are chosen as check sum entry. Assume that the value of switch which
is connected with 'm0' is 30 (1E) and the text of SerialTextField which is
connected with 'v0' is "cstest" (63,73,74,65,73,74). Then the
CHECK_SUM value of [CS] field will be 24 in decimal representation. (1E xor 63
xor 73 xor 74 xor 65 xor 73 xor 74 = 0x18 ; 24 in decimal)
ex) receiving
Assume that the serial data to receive is defined as above.
If a received data is
02,63,73,74,65,73,74,2C,1E,18,03
in Hexadecimal, the check sum value should be 0x18 (XOR value of every chosen
fields). If the tenth byte value of the received data is not 0x18 in
hexadecimal, the applet or application will dismiss the received data and it
will send NAK data if the NAK is specified in the receive protocol.
Note : Any data input with wrong format will be filtered off and will
not be accepted in any input fields.