JavaScript Function Glossary

Mosaic's WebSocket messaging library for the PDQ Board is complemented by the MosaicPDQ JavaScript API, implemented according to the revealing module pattern, that defines a single global object called MosaicPDQ. Functions are provided for opening a WebSocket connection to the PDQ Board, sending global variable values and function calls to the PDQ Board, updating element attributes and executing JavaScript functions based on WebSocket messages received from the PDQ Board, and logging status and exception messages to a text box on the page.

MosaicPDQ.getReadyState();

Returns the value of the readyState attribute of the WebSocket object representing the connection to the PDQ Board, which indicates the present status of the WebSocket connection. The possible return values are WebSocket.CONNECTING, WebSocket.OPEN, WebSocket.CLOSING, and WebSocket.CLOSED.

MosaicPDQ.log( msg );

Appends text to a textarea element on the page with an id attribute equal to log. This function is used internally by MosaicPDQ for displaying status and exception messages to the user, and may also be called by your application JavaScript code to insert application status messages if desired. The textarea element should be declared readonly; here is an example tag declaring a suitable textarea for log messages:

<textarea id="log" readonly="readonly" style="width:100%; resize:none;" rows="8"></textarea>

If you do not place a textarea in the page with id="log", messages will instead be logged to the browser console.

MosaicPDQ.sendArrayBin( nameOfVariable, arrayToSend, wbsktBinType);

This function is part of the binary extension to the websocket driver. Allows you to send an array of data as a binary websocket frame that can be received by the c handler Wbskt_Handle_Bin_Frame.
nameOfVariable is the name of the array that the data is destined for (declared with WBSKT_BIN_ARRAY in c code). wbsktBinType specifies what type of binary data is being sent. For binary arrays it should specify the data type and must be one of the following:
WBSKT_BIN_TYPE_ARRAY_INT8
WBSKT_BIN_TYPE_ARRAY_UINT8
WBSKT_BIN_TYPE_ARRAY_INT16
WBSKT_BIN_TYPE_ARRAY_UINT16
WBSKT_BIN_TYPE_ARRAY_INT32
WBSKT_BIN_TYPE_ARRAY_UINT32
WBSKT_BIN_TYPE_ARRAY_FLOAT32

If the size of the array being sent exceeds the size of the c array declared with WBSKT_BIN_ARRAY then an error will be issued from the c driver.

Availability: Mosaic IDE+ revision 1636 or greater

MosaicPDQ.sendEvent( event );

With a WebSocket connection already established, executes a function defined in C on the PDQ Board, with the name of the function to be executed specified in a string as the first argument event. The PDQ Board function to be executed must have been defined using the macro WBSKT_EVENT (see the C Function Glossary). Any arguments to be passed to the PDQ Board function are passed to MosaicPDQ.sendEvent() after the function name. The type of each argument must be one of the JavaScript types boolean, number, or string, and must match the type declared on the PDQ Board with WBSKT_EVENT. When the function is executed on the PDQ Board, any arguments that were passed to MosaicPDQ.sendEvent() as JavaScript type number will be interpreted as either long or float C type depending on the corresponding type specified in the arguments list of WBSKT_EVENT.

MosaicPDQ.sendMessage( message );

With a WebSocket connection already established, sends the single string argument message through the WebSocket connection by calling WebSocket.send( message ). Any exceptions thrown are caught and passed to MosaicPDQ.log(). Called internally by MosaicPDQ.sendEvent() and MosaicPDQ.sendValue().

MosaicPDQ.sendValue( name, value );

With a WebSocket connection already established, updates a global variable defined in C on the PDQ Board, with the name of the variable specified by first argument name and the new value specified by the second argument value. The global variable to be updated on the PDQ Board must have been declared with one of the macros WBSKT_BOOLEAN, WBSKT_LONG, or WBSKT_FLOAT (see the C Function Glossary). For a variable declared with WBSKT_BOOLEAN, the type of value in JavaScript must be boolean; For a variable declared with WBSKT_LONG or WBSKT_FLOAT, the type of value in JavaScript must be number.

MosaicPDQ.setPDQHostname( newHostname );

Prior to opening a WebSocket connection, specifies the hostname or IP address assigned to the EtherSmart Wildcard that is listening for WebSocket connections on a PDQ Board stack. This is not necessary if the HTML interface was loaded from the same EtherSmart Wildcard that is also listening for WebSocket connections. However, if the HTML interface is loaded from a separate server, or stored locally on the device running the browser, it is necessary to call this function to specify how to locate the EtherSmart Wildcard to which a WebSocket connection will be made, before calling MosaicPDQ.websocketConnect(). The single argument newHostname is a string specifying either the IP address of the EtherSmart Wildcard that is listening for WebSocket connections, or a DNS hostname that will resolve to its IP address.

MosaicPDQ.websocketConnect();

Opens a WebSocket connection to an EtherSmart Wildcard on a PDQ Board stack. If MosaicPDQ.setPDQHostname() has been called, will attempt to open a WebSocket connection to the IP address or hostname passed to MosaicPDQ.setPDQHostname(), otherwise attempts to open a WebSocket connection to the same IP address or hostname from which the HTML interface was loaded (the hostname attribute of the window.location object).

MosaicPDQ.websocketDisconnect();

Closes a presently-open WebSocket connection. If a WebSocket connection was open, this has the effect of changing the return value of MosaicPDQ.getReadyState() from WebSocket.OPEN to WebSocket.CLOSING, and sending a request to the EtherSmart Wildcard to close the WebSocket connection; when it is closed, the readyState value will change to WebSocket.CLOSED.