User Tools


Link to this comparison view

2.0:serial_interface [2015/09/16 02:00] (current)
Line 1: Line 1:
 +====== Serial Interface ======
 +
 +TruConnect provides a flexible serial interface.
 +The serial protocol for issuing commands and receiving responses can be used locally via the UART interface or remotely via the BLE interface. The protocol is easy to use for both humans and machines alike.  ​
 +
 +TruConnect also allows data to be streamed directly between the UART and BLE interfaces. ​
 +
 +The serial bus mode determines whether data is streamed, or which interface can send commands to TruConnect.
 +
 +For a demonstration of serial bus modes, bus mode selection, and remote control of a TruConnect device, see the [[.apps/​bus_mode_selection|Bus Mode Selection and Remote Control]] application note. 
 +
 +----
 +
 +
 +===== UART Protocol =====
 +
 +UART baud rate is determined by the [[variables#​ua_b|ua b]] variable. The default is ''​115200''​. ​
 +
 +UART flow control is determined by the [[variables#​ua_f|ua f]] variable. The default is ''​0'',​ no flow control.
 +
 +The serial port settings, corresponding to the TruConnect defaults, are 115200 8N1 with NO hardware flow control:
 +
 +  * Baud rate: ''​115200''​
 +  * Date: ''​8 bit''​
 +  * Parity: ''​none''​
 +  * Stop: ''​1 bit''​
 +  * Flow control: ''​none''​
 +  ​
 +See [[getting_started#​opening_a_truconnect_terminal|Getting Started, Opening a TruConnect Terminal]].
 +
 +
 +===== Serial Bus Modes =====
 +
 +A module running TruConnect can operate in any one of three distinct bus modes:
 +  * local COMMAND mode --- TruConnect commands are issued via the serial UART interface (the remote COMMAND interface is disabled)
 +  * STREAM mode --- data is transferred directly between the serial UART interface and the wireless BLE interface
 +  * remote COMMAND mode --- TruConnect commands are issued via the wireless BLE interface (the local COMMAND interface is disabled)
 +
 +The diagram below shows a schematic representation of the three bus modes.
 +
 +{{.serial_interface/​serial_bus_modes1.png?​900}}
 +
 +There are various ways to make TruConnect transition between bus modes including:
 +  * Assert a GPIO (manually via a push button or using a microcontroller)
 +  * Issue the [[.commands#​str]] command (when the module is in either local or remote command mode)
 +  * Set the TruConnect ''​mode''​ characteristic (using a remote BLE host such as an iOS/​Android/​Windows app or another TruConnect module)
 +
 +==== Manual and Automatic Bus Mode Selection ==== 
 +  ​
 +When a TruConnect device boots up, it may be desirable to control it via the UART interface, or by a remote BLE device. ​
 +
 +To allow for either option to work without further configuration,​ TruConnect supports a choice of **manual** and **automatic** bus mode selection. ​
 +
 +Bus mode selection depends on whether the ''​mode_sel''​ GPIO is configured. See the [[.commands#​gfu|gfu]] (GPIO function) command.
 +
 +^ mode_sel GPIO ^ Bus mode selection ​ ^ Description ^
 +| configured ​   | **manual** ​         |<​html>​
 +<ul>
 +<li class="​level1"><​div class="​li">​bus mode initializes to the value set by <a href="​.variables#​bu_i">​bu i</​a></​div></​li>​
 +<li class="​level1"><​div class="​li"><​code>​mode_sel</​code>​ GPIO determines if the bus is in STREAM mode or local COMMAND mode</​div></​li> ​
 +<li class="​level1"><​div class="​li">​if the bus is in STREAM mode, the remote device can use  the <​code>​mode</​code>​ characteristic to switch to remote COMMAND mode, if enabled. See <a href="​.variables#​sy_r_e">​sy r e</​a></​div></​li> ​
 +</​ul></​html>​|
 +|not configured | **automatic** ​      ​|<​html>​
 +<ul>
 +<li class="​level1"><​div class="​li">​if a remote device is connected: the bus is in STREAM mode</​div></​li>​
 +<li class="​level1"><​div class="​li">​if NO remote device is connected: the bus is in local COMMAND mode</​div></​li>​
 +<li class="​level1"><​div class="​li">​if the bus is in STREAM mode, the remote device can use  the <​code>​mode</​code>​ characteristic to switch to remote COMMAND mode, if enabled. See <a href="​.variables#​sy_r_e">​sy r e</​a></​div></​li> ​
 +</​html>​|
 +
 +The state diagrams below show the possible transitions.  ​
 +
 +=== Manual Bus Mode Selection ===
 +
 +{{.serial_interface/​state_diagram1.png?​700}}
 +
 +<!-- %%pageBreakAfter%% -->
 +
 +=== Automatic Bus Mode Selection ===
 +
 +{{.serial_interface/​state_diagram_no_mode_sel1.png?​700}}
 +
 +==== local COMMAND mode ====
 +
 +To enter local COMMAND mode:
 +
 +  * if **manual** bus mode is selected, either:
 +    * boot the module with the [[.variables#​bu_i|bu i]] (bus mode initialization) variable set to ''​command''​
 +    * assert/​toggle the ''​mode_sel''​ GPIO --- see the [[.commands#​gfu|gfu]] (GPIO function) command
 +  * if **automatic** bus mode is selected:
 +    * disconnect any remote device
 +  ​
 +See [[#​command_protocol|Command Protocol]] for details of sending commands and handling responses.
 +
 +==== STREAM mode ====
 +
 +To enter STREAM mode:
 +
 +  * if **manual** bus mode is selected, either:
 +    * boot the module with the [[.variables#​bu_i|bu i]] (bus mode initialization) variable set to ''​stream''​
 +    * with the module in local COMMAND mode, assert/​toggle the ''​mode_sel''​ GPIO --- see the [[.commands#​gfu|gfu]] (GPIO function) command.
 +  * if **automatic** bus mode is selected:
 +    * connect remote device  ​
 +  * issue the [[.commands#​str]] (stream) command
 +
 +In Stream mode, bytes or characters sent from the host to a serial interface are transparently pushed by TruConnect to the remote device via the wireless interface. ​
 +
 +Conversely, bytes or characters received from a remote device are transparently pushed by TruConnect to a serial interface connected to the host. 
 +
 +The [[getting_started|Getting Started]] example is a typical application that uses stream mode.
 +
 +<!-- %%pageBreakAfter%% -->
 +
 +==== remote COMMAND mode ==== 
 +  ​
 +To enter remote COMMAND mode:
 +  * Set the BLE ''​mode''​ characteristic to ''​REMOTE_COMMAND_MODE''​. ​
 +    * For remote control via a tablet or phone, see [[ble_connections#​truconnect_service_and_characteristics|Communicating via BLE, TruConnect Service and Characteristics]]. ​
 +    * For remote control via another TruConnect device, see the [[.commands#​rbmode|rbmode]] command. ​
 +    * The device to be controlled must have remote access enabled. See [[.variables#​sy_r_e|sy r e]].
 +**Note**: It is only possible to enter remote COMMAND mode with a remote host using the BLE interface, and only if the module is in STREAM mode. 
 +
 +See [[#​command_protocol|Command Protocol]] for details of sending commands and handling responses.
 +
 +
 +=====
 +
 +
 +----
 +
 +===== Command Protocol =====
 +
 +Both local COMMAND mode and remote COMMAND mode provide an asynchronous command interface that a host may use to send and receive control and setup information. Command mode is typically used by a host to configure TruConnect. ​
 +
 +Command mode is the primary mode used to configure TruConnect. Grasping how command mode works, and the options provided, is the key to mastering the use of TruConnect. The serial interface is designed to cater for humans and machines alike, and the interface is configurable to suit the needs of both.
 +
 +In Command mode, control, data and debug logs (if enabled) are interleaved. ​
 +
 +==== Configuration ====
 +
 +In command mode, TruConnect and the ACKme module effectively provides a slave interface to the host. The host is the master and TruConnect is the slave. The host initiates all transactions which follow the format of "host issues a command, TruConnect provides a response"​. TruConnect [[commands]] are used by the host to read and write TruConnect [[variables]],​ send control information,​ and send and receive data across network connections.
 +
 +The system command mode variable ([[variables#​sy_c_m|sy c m]]) is provided for convenience to make it easy to switch between human mode and machine mode. 
 +
 +Setting [[variables#​sy_c_m|sy c m]] to ''​human''​ or ''​machine''​ conveniently changes the value of each of the following variables to configure the desired command mode.
 +
 +<​BOOKMARK:​human_config>​
 +=== Human Friendly Command Mode ===
 +
 +By default, the serial interface is configured to be human friendly with the following settings. See [[variables#​system_list|System Variables]].
 +<​code>​
 +set sy c m human
 +</​code>​
 +is equivalent to:
 +<​code>​
 +set sy p all  -> Turn on all debug & informational prints
 +set sy c h 0  -> Disable response header
 +set sy c p 1  -> Turn on the user prompt
 +set sy c e 1  -> Turn on echo to see what you're typing
 +</​code>​
 +
 +<​BOOKMARK:​mcu_config>​
 +=== Machine Friendly Command Mode ===
 +
 +To configure the serial interface for machine friendly operation, use the following settings. See [[variables#​system_list|System Variables]].
 +<​code>​
 +set sy c m machine
 +</​code>​
 +is equivalent to:
 +<​code>​
 +set sy p 0    -> Turn off all debug & informational prints
 +set sy c h 1  -> Enable response header
 +set sy c p 0  -> Turn off the user prompt
 +set sy c e 0  -> Turn off echo
 +</​code>​
 +
 +==== Command Format ====
 +Commands sent to TruConnect are formatted as shown in the following table. The ''<​command name>''​ is a TruConnect command issued by the host, and ''​[variable name <​argument>​]\r\n''​ is an (optional) TruConnect variable name and accompanying argument terminated by a carriage return and newline character.
 +<​code><​command name> [variable name <​argument>​]\r\n </​code>​
 +
 +==== Response Format ====
 +Responses from TruConnect follow the format shown in the text below.
 +<​code>​
 +RXYYYYY\r\n
 +<​response data>
 +</​code>​
 +where ...
 +  * ''​R''​ denotes a Response header.
 +  * ''​X''​ is the error code (response error codes are listed below).
 +  * ''​YYYYY''​ is the response data length in bytes including a trailing ''​\r\n''​. The response data length is zero if no data is available, or >2 (including ''​\r\n''​) if data is available.
 +  * ''<​response data>''​. If the response data length is >0, the ''<​response data>''​ is the data returned from TruConnect in response to the command.
 +
 +=== Response Error Codes ===
 +
 +^  Code  ^   ​Description ​               ^    From Commands ​      ^
 +|       0| Success ​                     |    all                 ​| ​   ​
 +|       1| Command failed ​              ​| ​   all                 |
 +|       2| Parse error                  |    all                 |
 +|       3| Unknown command ​             |    all                 |
 +|       4| Too few args                 ​| ​   all                 |
 +|       5| Too many args                |    all                 |
 +|       6| Unknown variable or option ​  ​| ​   all                 |
 +|       7| Invalid argument ​            ​| ​   all                 |
 +|       8| Timeout ​                     |  [[commands#​con|con]] ​ |
 +|       9| Security mismatch ​           |  [[commands#​con|con]] ​ |
 +                                    ​
 +
 +==== Log Format ====
 +If [[.variables#​sy_c_p|sy c p]] (system print level) is greater than 0, a log header together with one or more informational debug logs may be returned in addition to a response header and response data when a command is issued. Log headers follow the format shown in the table below.
 +<​code>​
 +LXYYYYY\r\n
 +<log message>
 +</​code>​
 +where ...
 +  * ''​L''​ denotes a Log header.
 +  * ''​X''​ is the log level.
 +  * ''​YYYYY''​ is the log message length in bytes including a trailing ''​\r\n''​. Log messages are always >2 bytes in length and including terminating ''​\r\n''​ characters.
 +  * ''<​log message>''​. The log message returned by TruConnect in response to the command.
 +
 +===== Packet Size Limit =====
 +
 +TruConnect has a limitation on the size of BLE packets, related to the Tx UART FIFO size of 16 bytes. This packet size limit may become evident when sending bytes rapidly to a TruConnect BLE receiving device running at a lower BAUD rate than the transmitting BLE device. The workaround is to send no more than 15 bytes at once. 
 +
 +