Newer
Older
TestStandRepository / Software / Arduino / libraries / Arduino-Libraries / CmdMessenger / README.markdown
  1. # CmdMessenger v3.6
  2.  
  3. A serial messaging library for the Arduino and .NET/Mono platform
  4.  
  5. ## Introduction
  6.  
  7. CmdMessenger is a messaging library for the Arduino Platform (and .NET/Mono platform). Ituses the serial port as it's transport layer**
  8.  
  9. The message format is:
  10. ```
  11. Cmd Id, param 1, [...] , param N;
  12. ```
  13.  
  14. Although the field separator ',' and command separator ';' can be changed
  15.  
  16. The library can
  17. * both send and receive of commands
  18. * Both write and read multiple arguments
  19. * Both write and read all primary data types
  20. * Attach callback functions any received command
  21.  
  22. The library supports any primary data types, and zero to many multiple arguments. Arguments can either be sent in plain text (to be human readable) or in binary form (to be efficient).
  23.  
  24. With version 3.x also comes a full implementation of the toolkit in C#, which runs both in Mono (http://monodevelop.com/Download) and Visual Studio (http://www.microsoft.com/visualstudio/eng#downloads)
  25. This allows for full 2-way communication between the arduino controller and the PC.
  26.  
  27. \** but it could easily be modified to work over Bluetooth or a web interface.
  28.  
  29.  
  30. ## Requirements
  31.  
  32. * [Arduino IDE Version 1.0.5 or later](http://www.arduino.cc/en/Main/Software)*
  33.  
  34. \* Earlier versions of the Arduino IDE may work but have not been tested.
  35.  
  36. ## Getting Started
  37.  
  38. Get to know the library, by trying the examples,from simple to complex:
  39. ### Receive
  40. The 1st example will make the PC toggle the integrated led on the Arduino board.
  41.  
  42. * On the Arduino side, it demonstrates how to:
  43. - Define commands
  44. - Set up a serial connection
  45. - Receive a command with a parameter from the PC
  46. * On the PC side, it demonstrates how to:
  47. - Define commands
  48. - Set up a serial connection
  49. - Send a command with a parameter to the Arduino
  50.  
  51. ### SentandReceive
  52. This example expands the previous Receive example. The Arduino will now send back a status.
  53. On the Arduino side,
  54. * it demonstrates how to:
  55. - Handle received commands that do not have a function attache
  56. - Send a command with a parameter to the PC
  57. * On the PC side, it demonstrates how to:
  58. - Handle received commands that do not have a function attached
  59. - Receive a command with a parameter from the Arduino
  60.  
  61. ### SendandReceiveArguments
  62. This example expands the previous SendandReceive example. The Arduino will now receive multiple
  63. and sent multiple float values.
  64. * On the arduino side, it demonstrates how to:
  65. - Return multiple types status
  66. - Receive multiple parameters,
  67. - Send multiple parameters
  68. - Call a function periodically
  69. * On the PC side, it demonstrates how to:
  70. - Send multiple parameters, and wait for response
  71. - Receive multiple parameters
  72. - Add logging events on data that has been sent or received
  73. ### SendandReceiveBinaryArguments
  74.  
  75. This example expands the previous SendandReceiveArguments example. The Arduino will receive and send multiple
  76. Binary values, demonstrating that this is more efficient way of communication.
  77.  
  78. * On the Arduino side, it demonstrates how to:
  79. - Send binary parameters
  80. - Receive binary parameters
  81. * On the PC side, it demonstrates how to:
  82. - Receive multiple binary parameters,
  83. - Send multiple binary parameters
  84. - How callback events can be handled while the main program waits
  85. - How to calculate milliseconds, similar to Arduino function Millis()
  86.  
  87. ### DataLogging
  88.  
  89. This example expands the previous SendandReceiveArguments example. The PC will now send a start command to the Arduino, and wait for a response from the Arduino. The Arduino will start sending analog data which the PC will plot in a chart
  90.  
  91. This example shows how to :
  92.  
  93. - Use CmdMessenger in combination with GUI applications
  94. - Use CmdMessenger in combination with ZedGraph
  95. - Use the StaleGeneralStrategy
  96. ### ArduinoController
  97.  
  98. This example expands the SendandReceiveArguments example. The PC will now sends commands to the Arduino when the trackbar is pulled. Every TrackBarChanged events will queue a message to the Arduino to set the blink speed of the internal / pin 13 LED
  99.  
  100. This example shows how to :
  101.  
  102. - use CmdMessenger in combination with GUI applications
  103. - use CmdMessenger in combination with ZedGraph
  104. - Send queued commandssds
  105. - use the CollapseCommandStrategy
  106.  
  107. ### TemperatureControl
  108.  
  109. This example expands the previous ArduinoController example. The PC will now send a start command to the Arduino, and wait for a response from the Arduino. The Arduino will start sending temperature data and the heater steering value data which the PC will plot in a chart. With a slider we can set the goal temperature, which will make the PID software on the controller adjust the setting of the heater.
  110. This example shows how to design a responsive performance UI that sends and receives commands
  111. - Send queued commands
  112. - Add queue strategies
  113.  
  114. ### ConsoleShell
  115.  
  116. This example shows how to use CmdMessenger as a shell, and communicate with it using the Serial Console
  117. This example is different from the others:
  118.  
  119.  
  120. - there is no PC counterpart
  121. - it will only receive commands, instead of sending
  122. - commands it will use Serial.Print
  123.  
  124. Below is an example of interacting with the sample:
  125. ```
  126. Available commands
  127. 0; - This command list
  128. 1,<led state>; - Set led. 0 = off, 1 = on
  129. 2,<led brightness>; - Set led brighness. 0 - 1000
  130. 3; - Show led state
  131. Command> 3;
  132. Led status: on
  133. Led brightness: 500
  134. Command> 2,1000;
  135. Led status: on
  136. Led brightness: 1000
  137. Command> 1,0;
  138. Led status: off
  139. Led brightness: 1000
  140. ```
  141.  
  142. All samples are heavily documented and should be self explanatory.
  143. 1. Open the Example sketch in the Arduino IDE and compile and upload it to your board.
  144. 2. Open de CmdMessenger.sln solution in Visual Studio or Mono Develop/Xamarin Studio
  145. 3. Set example project with same name as the Arduino sketch as start-up project, and run
  146. 4. Enjoy!
  147.  
  148. ## Trouble shooting
  149. * If the PC and Arduino are not able to connect, chances are that either the selected port on the PC side is not correct or that the Arduino and PC are not at the same baud rate. Try it out by typing commands into the Arduino Serial Monitor, using the ConsoleShell
  150. * Some boards (e.g. Sparkfun Pro Micro) need DtrEnable set to be true.
  151. * If the port and baud rate are correct but callbacks are not being invoked, try looking at logging of sent and received data. See the SendandReceiveArguments project for an example.
  152. * If you have a problem that is hard to pinpoint, use the CommandMessengerTests testsuite. This project runs unit tests on several parts on the mayor parts of the CmdMessenger library. Note that the primary function is not to serve as an example, so the code may be less documented and clean as the example projects.
  153.  
  154.  
  155. ## Notes
  156. An example for use with Max5 / MaxMSP was included up until version 2. (it can still be found here https://github.com/dreamcat4/CmdMessenger).
  157. Since we have not been able to check it wil Max/MaxMSP, the example was removed.
  158.  
  159. ## Changelog
  160.  
  161. ### CmdMessenger v3.6
  162. * [Arduino] Bugfix: approx 1 in 1000 commands failed, when multiple binary parameters are sent over
  163. * [Arduino] Bugfix: Binary sending of non-number would give compile time error
  164. * [Arduino] feature: Posibility to send command without argument
  165. * [Arduino] feature: Posibility to send floats with scientific notation, to get full float range
  166. * [.Net/.Mono] Added Unit tests
  167. * [.Net/.Mono] Consistent variables on .NET and Arduino side.
  168. * [.Net/.Mono] Major performance improvement (for boards like Teensy 3), by combining queued commands
  169.  
  170. ### CmdMessenger v3.5
  171. * [Arduino] Added console shell sample
  172. * [Arduino] Minor performance improvement
  173. * [.Net/.Mono] Minor performance improvement
  174.  
  175. ### CmdMessenger v3.4
  176. * [Arduino] Bug-fix in receiving binary values
  177. * [.Net/.Mono] Bug-fix that makes communication 100x (!) faster, while lowering system load
  178. * [.Net/.Mono] Added function to run on single core
  179.  
  180. ### CmdMessenger v3.3
  181. * [Arduino] Speed improvements for Teensy
  182.  
  183. ### CmdMessenger v3.2
  184. * [All] Clean transport layer interface makes it easy to implement other transport modes
  185. (Bluetooth, ZigBee, Web), even if they do not implement a virtual serial port
  186. * [.Net/.Mono] Adaptive throttling to work with transport layers of any speed
  187. * [.Net/.Mono] Smart queuing for smooth running applications and no hanging UI
  188. * [Arduino] Small fixes and sending long argument support
  189.  
  190. ### CmdMessenger v3.1
  191. * Adds 2 GUI examples
  192.  
  193. ### CmdMessenger v3.0
  194.  
  195. * Wait for acknowlegde commands
  196. * Sending of common type arguments (float, int, char)
  197. * Multi-argument commands
  198. * Escaping of special characters in strings
  199. * Sending of binary data of any type (uses escaping, no need for Base-64 Encoding)
  200. * Bugfixes
  201. * Added code documentation
  202. * Added multiple samples
  203.  
  204. ### CmdMessenger v2
  205.  
  206. * Updated to work with Arduino IDE 022
  207. * Enable / disable newline (print and ignore)
  208. * New generic example (works with all Arduinos)
  209. * More reliable process() loop.
  210. * User can set their own cmd and field seperator
  211. (defaults to ';' and ',')
  212. * Base-64 encoded data to avoid collisions with ^^
  213. * Works with Arduino Serial Monitor for easy debugging
  214.  
  215. ## Credit
  216.  
  217. * Initial Messenger Library - Thomas Ouellet Fredericks.
  218. * CmdMessenger Version 1 - Neil Dudman.
  219. * CmdMessenger Version 2 - Dreamcat4.
  220. * CmdMessenger Version 3 - Thijs Elenbaas
  221.  
  222. ## Copyright
  223.  
  224. CmdMessenger is provided Copyright © 2013,2014 under MIT License.
  225.