Many controls let you send serial commands to an Arduino, or other connected device. The commands are sent when the user does something with the control: clicking on a Button, changing a NumericUpDown control or ticking a CheckBox, for example. Each action raises an event which can send a serial message.

Use the Smart tag or Property editor in the Interface Designer to set the command that is sent to a connected device when an event occurs. You can enter the command message directly, or click on the ellipsis button (…) to open the Message Editor window.

Show the serial message editor

Click the ellipsis (…) button  to display the message editor.

Command Elements

Commands are strings built from three things:

  1. Text: plain text is sent unchanged to your Arduino
  2. Escape characters: escape characters start with a backslash (\) and are translated before being sent
  3. Expressions: expressions contain references to control properties and are evaluated before being sent. Expressions are surrounded by square brackets ([…])

Command strings can be used in any property that sends messages to connected devices. These properties start with the word On. Properties which send messages include OnClickSend for button controls, OnTextChangedSend for text-box controls and OnValueChangedSend for numeric up/down controls.

Example command strings
Message stringDescription
Hello world!Sends the text Hello world! to the connected device
Hello\r\nWorldThe escape characters \r and \n are turned into carriage return and newline bytes. So we send:
Hello
World
SetTemp [Temp.Value]The expression Temp.Value refers to the value property of a control named Temp. The whole expression will be replaced by the control value. So if the Temp control’s Value property is 42, we send: SetTemp 42

Message Editor

The Message Editor window provides an easy way to edit command messages. Open the Message Editor using the ellipsis button (…) found at the end of any message property.

The Message Editor includes:

  • a text area for entering commands
  • a drop-down menu which lists all the controls and properties available on the Interface Panel. Selecting one of these properties will insert the correct expression into the text area for you to edit
  • a Test button which will evaluate any expressions and show you the message that would be sent. You can display the result in ASCII or raw bytes.
Message Editor Window

Enter the command to be sent on a control event using the Message Editor window.

Escape Characters

Any backslash characters in a command message (but not within expressions) are treated as the start of an escape character. Escape characters are replaced before the message is sent.

Escape characters supported by command messages
Escape CharacterValueDescription
\r0x0ANewline
\n0x0DCarriage return
\t0x09Tab
\\0x0DBackslash
\xXX0xXXHexadecimal literal value

Expressions

Expressions in message commands must be surrounded by square-brackets ([…]). Just before the message is sent, the content of the square brackets is evaluated, converted to a string and inserted into the message. Expressions are evaluated before escape characters so any escape characters generated by the expression will be processed before the message is sent.

Expressions are processed by DynamicExpresso and support a small subset of the C# language.

Referencing Control Properties

The most common use for expressions is including values from control properties. For example, you might want to include the current value of a NumericUpDown control in a message sent when a Button control is clicked.

The syntax to use for runtime properties is: ControlName.PropertyName

Any runtime property of a control can be assessed in this way. You can find a list of the runtime properties of a control on its reference page.

Referencing Control Methods

Some controls (such as the Button) support runtime methods. These methods often take some parameters and return a result. A TextBox control, for example, includes a FixedLengthText(MaxLength) method which limits the length of the text included in the message.

The syntax to use for calling runtime methods is: ControlName.MethodName(Parameter1, Parameter2, …)

Any runtime method of a control can be accessed in this way. You can find a list of the runtime methods of a control on its reference page.

String Conversion

The expression engine automatically converts expression results to strings before combining them with any other text in the message. However, you can do this conversion yourself if you need more control over the format. For example, to send the value from a numeric control named Temp in 4 hexadecimal characters you can use: [((UInt32)Temp.Value).ToString("X4"))].

The ToString function can be applied to all values. Refer to Microsoft's documentation for more information on standard and custom formats.

Tools

Tools is a special object that provides a number of utility functions for generating methods.

Tools functions
FunctionExampleDescription
ToInt(Decimal Value)[Tools.ToInt(Temp.Value).ToString("X")]NumericUpDown controls Value property is a Decimal. The ToInt(…) function converts it to a 32-bit integer. It is equivalent to ((Int32)Temp.Value). This is useful if you need to send hexadecimal values (Decimals can't easily be converted to hexadecimal values). ToString("X") converts an integer to a hexadecimal string.
AsByte(Type Value)[Tools.AsByte((UInt16)Temp.Value)]Converts a numeric value to literal byte values (\xFF, for example). Type can be byte, sbyte, Int16, Int32, Int64, UInt16, UInt32, UInt64, char, float and double. Multi-byte values are written in little-endian order. Cast to be sure you get the number of bytes expected.
Choose(int Index, String s0, String s1, …, String s9)[Tools.Choose(3, "A", "B", "C", "D")] returns "D"Select from a list of strings by index. Index is 0 based, so the first string is selected with an Index of 0, the second string with an Index of 1 and so on. Up to 10 strings can be included in the list

Operators

Expressions can include mathematical and logical operators. These can be useful for scaling or transforming control values. For example, the expression [Temp.Value*10] will multiply the value in a control named Temp by 10. Results from expressions are automatically converted to strings before they are sent.

Supported operators
OperatorDescription
+ - !Addition, subtraction, logical not
* / %Multiplication, division, modulus (remainder)
< > <= >=Less than, greater than, less than or equal, greater than or equal
== !=Equal, not equal
&& ||Logical And, Logical Or
?:Conditional selector

Literals

Literals are basic values: numbers, strings and logical values.

All numbers are 32-bit integers unless they include a decimal point. Numbers that include a decimal point are treated as doubles. Normal C# type promotion rules apply (so an integer multiplied by a double will be promoted to a double).

By default, all numbers are base-10. You can insert hexadecimal literals using the prefix 0x.

To create literals of a particular size, use a cast as in (Int16)42.

Supported literal types
TypeSizeDescription
Int648 bytesSigned, 64-bit integer
Int324 bytesSigned, 32-bit integer
Int162 bytesSigned, 16-bit integer
sbyte1 bytesSigned, 8-bit integer
UInt648 bytesUnsigned, 64-bit integer
UInt324 bytesUnsigned, 32-bit integer
UInt162 bytesUnsigned, 16-bit integer
byte1 bytesUnsigned, 8-bit integer
double8 bytesDouble precision floating point number
float4 bytesSingle precision floating point number
char1 byteSingle character
StringSequence of characters

String literals are surrounded by double quotes ("string", for example); character literals are surrounded by single quotes ('a', for example). Both string and character literals can use escape characters.

Escape characters supported inside string and character literals
ValueDescription
\'single quote
\"double quote
\\backslash
\0null character (0x00)
\aalert character (0x07)
\bbackspace character (0x08)
\fform-feed character (0x0C)
\nnewline character (0x0A)
\rcarriage return character (0x0D)
\ttab character (0x09)
\vvertical quote character (0x0B)

Start typing and press Enter to search