Many controls let you send serial messages to an Arduino, or other connected device. Messages 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.
Serial messages are typically processed on your Arduino using a command handler, which decodes the message and takes some action. The command handler in our Arduino library can decode messages sent using the bang protocol, then dispatch them to registered functions in your Arduino sketch. However, you can implement your own protocol and command handler if you prefer. The code example window parses messages to automatically generate boiler plate code that handles commands sent using the bang protocol.
Use the Smart tag or Property editor to set the command sent to a connected device when an event is triggered. You can enter the command message directly, or click on the ellipsis button (…) to open the Command Editor window.
Click the ellipsis (…) button to display the command editor.
Command Elements
Commands are strings built from four things:
- Text: plain text is sent unchanged to your Arduino
- Escape characters: escape characters start with a backslash (
\) and are translated before being sent - Expressions: expressions contain references to control properties and are evaluated before being sent. Expressions are surrounded by square brackets (
[…]) - Statements: statements are like expressions but their result is not included in the message sent. Statements are surrounded by braces (
{…})
Multi-line command strings are split into lines before they are sent. Each line is sent separately with a small delay (50 ms) between them to provide connected devices with small serial buffers time for parsing and processing. Multi-line commands don’t automatically include new-line characters. Use escape characters to include new-line/line-feed in a serial message.
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.
| Message string | Description |
|---|---|
!StartMotor\r\n |
Sends the text StartMotor followed by a carriage return and new line character. The escape characters \r and \n are converted into carriage return and newline bytes. |
!SetTemp [Temp.Value]\r\n |
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 |
!SetFlags [Flags.IntegerValue.ToString("X4")]\r\n |
The expression Flags.IntegerValue refers to the integer value property of a numeric up/down control named Flags. Calling the ToString("X4") will convert the integer value to a string formatting it as a 4 character hexadecimal value. So if the Flag control’s IntegerValue property is 160, we send: !SetFlags A0 |
!SetConfig [Velocity.Value*10] [AccelerationDistance.Value*10]\r\n |
Messages can include multiple expressions; expressions can perform simple arithmetic. |
!StartMotor\r\n{StopMotor.Enabled=true} |
Sends a start motor command and enables the control named StopMotor |
!SetUser [txtUser.Text]\r\n |
Multi-line messages are sent one line at a time with a small delay (50 ms) between each. |
Command Editor
The Command Editor window provides an easy way to edit command messages. Open the Command Editor using the ellipsis button (…) found at the end of any message property.
The Command Editor includes:
- a text area for entering commands; type Enter to add a new line to a multi-line message.
- 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 drop-down menu with common escape characters. Selecting an escape character will add it to your message.
- 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.
Use the command editor to build up messages for MegunoLink to send in response to control events.
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 Character | Value | Description |
|---|---|---|
| \r | 0x0A | Newline |
| \n | 0x0D | Carriage return |
| \t | 0x09 | Tab |
| \\ | 0x5C | Backslash |
| \xXX | 0xXX | Hexadecimal literal value |
Common escape characters can be inserted into the message from the drop-down menu.
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.
Properties and methods available for messages are listed for each control in the drop-down menu.
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: [Temp.IntegerValue.ToString("X4")].
The ToString function can be applied to all values. Refer to Microsoft’s documentation for more information on standard and custom formats.
Byte Conversion
MegunoLink normally sends values as strings. Use the BitConverter.GetBytes(…) to send data as byte values. For example: [BitConverter.GetBytes(num.IntegerValue)].
Byte values are in little-endian order; use Reverse to switch to big-endian byte order. For example: [BitConverter.GetBytes(num.IntegerValue).Reverse()].
GetBytes can be used with boolean, char, double, single, Int16, Int32, Int64, UInt16, UInt32 and UInt64 values.
Tools
Tools is a special object that provides a number of utility functions for generating methods.
Tools functions
| Function | Example | Description |
|---|---|---|
| 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. |
| ToInt(Type Value) | [Tools.ToInt(Temp.Value)] |
Converts a double or decimal numeric value to an integer value. Type can be double or decimal. |
| 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.
| Operator | Description |
|---|---|
| + – ! | 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.
| Type | Size | Description |
|---|---|---|
| Int64 | 8 bytes | Signed, 64-bit integer |
| Int32 | 4 bytes | Signed, 32-bit integer |
| Int16 | 2 bytes | Signed, 16-bit integer |
| sbyte | 1 bytes | Signed, 8-bit integer |
| UInt64 | 8 bytes | Unsigned, 64-bit integer |
| UInt32 | 4 bytes | Unsigned, 32-bit integer |
| UInt16 | 2 bytes | Unsigned, 16-bit integer |
| byte | 1 bytes | Unsigned, 8-bit integer |
| double | 8 bytes | Double precision floating point number |
| float | 4 bytes | Single precision floating point number |
| char | 1 byte | Single character |
| String | — | Sequence 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.
| Value | Description |
|---|---|
| \’ | single quote |
| \” | double quote |
| \\ | backslash |
| \0 | null character (0x00) |
| \a | alert character (0x07) |
| \b | backspace character (0x08) |
| \f | form-feed character (0x0C) |
| \n | newline character (0x0A) |
| \r | carriage return character (0x0D) |
| \t | tab character (0x09) |
| \v | vertical quote character (0x0B) |
