Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Comm Module

The Comm Module is used to control the functionality of the devices communication (serial) port; the way RhoElements interacts with that port and the data it provides.

Syntax

comm (Module) <META> Syntax

<META HTTP-Equiv="Comm" content="[parameter]">

<META HTTP-Equiv="Comm" content="CommEvent:url('[jsFunction | url]')">

Comm JavaScript Object Syntax:
By default the JavaScript Object 'comm' will exist on the current page and can be used to interact directly with the comm.
To Invoke comm methods via JavaScript use the following syntax: comm.method();

e.g. comm.open();
To Set comm parameters via JavaScript use the following syntax: comm.parameter = 'value'; remembering to enclose your value in quotes where appropriate.

e.g. comm.baudRate = 'value';
To Set comm return events via JavaScript use the following syntax: comm.event = JavaScript Function;

e.g. comm.commEvent = 'doFunction(%json)';

For more details on the event syntax and parameters see the Retrieval Events page.
To set multiple EMML parameters / events on a single line use the following syntax: comm.setEMML("[Your EMML Tags]");

e.g. comm.setEMML("baudRate:value;commEvent:url('JavaScript:doFunction(%json)');open");
Comm Ruby Object Syntax:
By default the Ruby Object 'Comm' will exist on the current page and can be used to interact directly with the Comm. All Methods, Parameters and Events are the same as JavaScript, however, notice 'Comm' needs to start with an uppercase letter. Another difference in Ruby is that methods do not end in '()'
To Invoke Comm methods via Ruby use the following syntax: Comm.method()

e.g. Comm.open
To Set Comm parameters via Ruby use the following syntax: Comm.parameter = 'value' remembering to enclose your value in quotes where appropriate.

e.g. Comm.baudRate = 'value'
To Set Comm return events via Ruby use the following syntax: Comm.event = url_for(:action => :event_callback)

e.g. Comm.commEvent = url_for(:action => :comm_event_callback)

For more details on the event syntax and parameters see the Retrieval Events page.

To access the event parameters in a Ruby callback function, you reference the @params object within the callback function. This object is simply a ruby hash {"parameter1 name" => "parameter1 value", "parameter2 name" => "parameter2 value", ...}

Methods

Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name Description Default Value
open Opens the COM port using applied settings. Closed
close Closes the currently open COM port, if any. Closed

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Name Possible Values Description Default Value
baudRate:[Value] 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 115200, 128000, 256000 Sets the baud rate of the serial port. (not all values are supported on all devices) 9600
dataBits:[Value] Integers between 5 and 9 inclusive. Sets the number of data bits per word on the device serial port (not all values are supported on all devices). 8
stopBits:[Value] '1', '1.5', '2'. Sets the number of stop bits per word on the device serial port (not all values are supported on all devices). 1
parity:[Value] 'Even', 'Odd', 'Mark', 'Space', 'No Parity' Sets the parity check type for the device serial port. (not all values are supported on all devices) 'No Parity'
handshake:[Value] 'HW' - Hardware Handshake, 'SW' - Software Handshake, 'None' - No handshake Sets the handshaking for the device serial port. (not all values are supported on all devices) 'None'
port:[Value] The device comm port, in the format COMn Sets the device serial port. (only certain port designations are valid on any given device) 'COM1'
chars:[Value] Positive number. Data will be received by RhoElements after the specified number of characters have been received over the COM port. RhoElements will receive the data in either a CommEvent or as keystrokes. 'Chars', 'EndChar' and 'Time' are mutually exclusive, see remarks. 'EndChar:CRLF'
endChar:[Value] Character code expressed as a decimal or 'CRLF' to specify Carriage return + Line Feed Data will be received by RhoElements after the specified character (or Carriage return + Line Feed) has been received over the COM port. RhoElements will receive the data, minus the final CRLF, in either a CommEvent or as keystrokes. 'Chars', 'EndChar' and 'Time' are mutually exclusive, see remarks. 'EndChar:CRLF'
time:[Value] Milliseconds Data will be received by RhoElements after the specified period of COM port inactivity has elapsed. RhoElements will receive the data in either a CommEvent or as keystrokes. 'Chars', 'EndChar' and 'Time' are mutually exclusive, see remarks. 'EndChar:CRLF'
writeBytes:[Value] A string of bytes, each byte represented as '%hh' where 'h' is a hexidecimal digit. A delimiter is optional and may be any character Value is converted to an array of bytes and written to the COM port. N/A
writeString:[Value] String Writes the specified string to the COM port. N/A
writeFile:[Value] Filename and Path The specified file is opened and its contents is written to the COM port. N/A
autoEnter:[Value] Enabled or Disabled Provided no CommEvent is defined and the received data is being received as keystrokes each block received will have a CR (Carriage Return) character appended to it. Disabled
autoTab:[Value] Enabled or Disabled Provided no CommEvent is defined and the received data is being received as keystrokes each block received will have a tab character appended to it. Disabled

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.


commEvent

This event is used to read data from the COM port and is triggered in response to a port event. Port events can be one of ‘Chars’, ‘EndChar’ or ‘Time’ as described in the Parameters section. If no CommEvent is defined the associated data is output as keystrokes.

ID Name Description
1 data The data that has been accumulated from the open communications port since the last time data was returned.

Remarks

General

If any of the parameters (e.g. BaudRate) are set whilst the COM port is open they will not take effect until the port is closed and reopened again. The parameters ‘Chars’, ‘EndChar’ and ‘Time’ are mutually exclusive and the last one set will take priority when the COM port is next opened.

AutoEnter and AccelerateKey

The AccelerateKey Meta tag controls the behaviour of Accelerate keys on Windows CE, if the Enter key is configured to be non functional then AutoEnter will also appear to not function either

Requirements

RhoElements Version 1.0.0 or above
Supported Devices All supported devices that have a COM port
Minimum Requirements COM Interface.
Persistence This tag is mostly page persistent, however when navigating to a new page the port will be closed and the CommEvent cleared. You will need to re-register the CommEvent and open the port again on the new page to continue serial port communication.

HTML/JavaScript Examples

The following example opens up the COM1 port using META tags, and instructs the Comm module to call the ‘ProcessData’ JavaScript function after 250 ms of port inactivity, passing the received data to the function. The port will be closed when RhoElements navigates to a new page.

<HTML>
   <HEAD>
   <!-- Setup the port -->
   <META HTTP-Equiv="Comm" Content="Port:COM1">
   <META HTTP-Equiv="Comm" Content="BaudRate:9600">
   <META HTTP-Equiv="Comm" Content="DataBits:8">
   <META HTTP-Equiv="Comm" Content="StopBits:1">
   <META HTTP-Equiv="Comm" Content="Parity:'No Parity'">
   <META HTTP-Equiv="Comm" Content="HandShake:None">
   <META HTTP-Equiv="Comm" Content="Time:250">
   <META HTTP-Equiv="Comm" Content="CommEvent:url('JavaScript:ProcessData('%s');')">
   <META HTTP-Equiv="Comm" Content="Open">

   <!-- Function called when data received from the port -->
   <SCRIPT TYPE="text/javascript">
      function ProcessData(data)
      {
         alert(data);
      }
   </SCRIPT>
   </HEAD>

   <BODY>
   <!-- Your page goes here -->
   </BODY>
</HTML>

The following example sets up the communications port and opens it using JavaScript and the generic ActiveX object. This example sets the event trigger to be the receipt of the ‘#’ character (char code = 35). The default port parameters are used. JavaScript routines for writing to the port and closing it are also included.

<HTML>
   <HEAD>
   <!-- Script that will get called on page load -->
   <SCRIPT TYPE="text/javascript">

   var objGeneric;

   function DisplayData(data)
   {
      alert("Received the following data on the Comm port: " + data);
   }

   function CommSetup()
   {
      comm.endChar = 35;
      comm.commEvent = url('JavaScript:DisplayData('%s');');
      comm.open();
   }

   function CommWrite()
   {
      //  Write a string to the COM port
      comm.writeString = 'StringToWrite';
      //  Write bytes to the COM port
      comm.writeBytes = '%62 %79 %74 %65 %20 %6d %65 %0a';
      //  Write a file to the COM port
      comm.writeFile = '\\File Path\\FileToWrite.txt';
   }

   function CommClose()
   {
      comm.close();
   }
   </SCRIPT>
   </HEAD>

   <BODY onload="CommSetup()">
   <!-- Your page goes here -->
   </BODY>
</HTML>
Back to Top