JavaScript COM API
From SpinetiX Support Wiki
Introduction
The JavaScript COM API allows interacting with devices connected via the serial port directly from the JavaScript code. It was experimentally introduced within firmware 3.0.0 and stabilized within firmware 3.1.0 for legacy players.
This API defines how to send messages to the external device and how to handle incoming messages from the external device via the serial port. The serial port settings can be modified from Control Center.
writeCOMPort()
void writeCOMPort( in DOMString text );
void writeCOMPort( in Array bytes );
void writeCOMPort( in ArrayBuffer typedArray );
void writeCOMPort( in Buffer buffer );
There are different ways to specify the characters to be sent on the serial port.
- A string, which is convenient for text based protocols. Note that it is not possible to send a zero byte when using a string argument, and that each Unicode character code is truncated to 8 bits. Use the Buffer variant if you need to encode non ASCII characters.
-
writeCOMPort( "Hello World !\r\n" );
-
- An array of byte values. The array elements are first cast to an integer number, then truncated to 8 bits.
-
writeCOMPort( [ 0, 1, 2, 3 ] );
-
- An ArrayBuffer typed array (e.g., Uint8Array object), the binary content of which is sent verbatim.
- A Buffer object which is convenient to format packet structures with any combination of numbers, encoding and byte orders.
-
var buf = new Buffer( 256 ); buf.writeUInt32LE( 0xbadcaffe, 0 ); buf.write( "Hello", 4, 32, "utf8" ); writeCOMPort( buf );
-
com events
To read data from the serial port, simply add an event listener for the "com" event on the document object. The COMEvent object that is passed to the callback function has the following attributes:
-
bytes- Uint8Array typed array with content read from the serial port.
-
data- Buffer object with content read from the serial port.
-
portNumber- This is always set to 1.
Example:
document.addEventListener( "com", function( ev ) {
alert( 'received: ' + ev.data.toString() );
alert( 'first byte is: ' + ev.bytes[0] );
});
Support in HTML5
It is possible to use the JavaScript COM API within web page layers, starting with DSOS 4.7.0 and Elementi 2021 Update 5. To enabled it, use the "allow" attribute (i.e., allow="spx-api") on the web page layer. Within the HTML5 code, you can call the above methods on the spx global object, something like this:
document.addEventListener("DOMContentLoaded", () => {
spx.writeCOMPort("Hello World from HTML !\r\n");
});