C Function Glossary

Software development using the WebSocket messaging library involves "catching" data that is sent by the browser, and preparing data to be sent. The WebSocket messaging library in C is made available by adding #include <websocket.h> to a C source code file. Note that macros defined in the WebSocket messaging library assume that the EtherSmart/WiFi Wildcard driver is also available, i.e. that your source code file also includes the line #include <wwifi.h>.

unsigned Wbskt_Array_LoadFrame_Bin(
    const xaddr xbuffer,             const unsigned maxbytes,
    const char *js_str_name,         const uint8_t size_of_element,
    const uint16_t size_of_array,         const xaddr array_to_load,
    const uint8_t wbskt_bin_type                        );

This function is part of the binary extension to the websocket driver. Builds a mosaic websocket binary frame suitable for interpretation by the MosaicPDQ JavaScript API. The websocket binary frame is intended to be the payload of WebSocket binary array, at a buffer that begins at the 32-bit extended address xbuffer in PDQ Board RAM, and that doesn't exceed maxbytes. If the websocket binary frame is of length less than maxbytes, Wbskt_Array_LoadFrame_Bin will return the length of the websocket binary frame (in bytes). If the resulting websocket binary frame length equals or exceeds maxbytes, it will not be completely written to the buffer and the return value will be equal to zero. The data will be placed into the variable js_str_name on the receiving side. When used with the MosaicPDQ JavaScript API make sure the receiving variable is an array and has the property "MosaicWritable" set to true as shown below.

var varName = [];
varName.MosaicWritable = true;

size_of_element is the size of each element in the array to send. For example, you could put sizeof( float ) into this parameter. size_of_array is the size of the entire array. For example, if your float array has 5 elements you could put 5*sizeof( float ) into this parameter. array_to_load is the C name of the array that will be sent. wbskt_bin_type 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

The paged RAM buffer provided by the EtherSmart Wildcard driver software at location specified by Ether_Outbuf() with size specified by Ether_Outbufsize() (see EtherSmart Wildcard driver glossary) is suitable for use in your application code for assembling outgoing WebSocket messages. The assembled message may be sent using the EtherSmart Wildcard driver function WS_Send_Frame_Bin().

Availability: Mosaic IDE+ revision 1636 or greater

 unsigned Wbskt_Bin_Init(); 

This function is part of the binary extension to the websocket driver. Initializes the system to be ready to add websocket arrays using Wbskt_Bin_Activate_##NAME function. This function must be called before activating any websocket arrays and before receiving any websocket arrays. Wbskt_Init must still be called before any websocket functions are performed (regardless if they are regular text-based websocket frames or part of the binary extension).

Availability: Mosaic IDE+ revision 1636 or greater

 WBSKT_BIN_ARRAY( NAME, NUM_ELEM, TYPE ); 

This function is part of the binary extension to the websocket driver. Creates an array suitable for receiving arrays from incoming binary websocket frames created in the MosaicPDQ JavaScript library. NAME is the name of the variable. NUM_ELEM is the number of elements in the array. TYPE is the c data type of the array (like float or char).

This is a macro that defines various data types and an activation function. First, a volatile array of type TYPE is created with NUM_ELEM number of elements. This array can be accessed directly by the programmer. Second, a struct WSArrayHead named wbskt_array_head_##NAME is created (note, NAME is from the macro parameter list and is concatenated with "wbskt_array_head_"). This structure holds the size of the array (wbskt_array_head_##NAME.size), a pointer to the array (wbskt_array_head_##NAME.array_ptr), and the status of the array (wbskt_array_head_##NAME.status). This structure is used by the handler Wbskt_Handle_Bin_Frame and can be accessed by the programmer. The status is a bitwise variable and be can read using regular c methods ( & (bitwise AND) the status with one of the below masks. What will remain is a 1 or 0 in that position with all other bits 0. You can feed this result directly into a conditional function like if). wbskt_array_head_##NAME.status should be written to with SetBits() or ClearBits() with one of the following masks:

WBSKT_BIN_STATUS_LOCK_AND_DENY
WBSKT_BIN_STATUS_WRITING_ENDED

Setting the status bit at WBSKT_BIN_STATUS_LOCK_AND_DENY will cause Wbskt_Handle_Bin_Frame to not write to the array as long as its set. The data received during this time is lost. This may be useful if you are currently performed operations on the array and don't want the data to change. In that case you would first call SetBits( WBSKT_BIN_STATUS_LOCK_AND_DENY, wbskt_array_head_##NAME.status); and once you are done performing operations on the data call ClearBits( WBSKT_BIN_STATUS_LOCK_AND_DENY, wbskt_array_head_##NAME.status);. WBSKT_BIN_STATUS_WRITING_ENDED is set every time Wbskt_Handle_Bin_Frame finishes writing to the array. If WBSKT_BIN_STATUS_LOCK_AND_DENY is not set, you can determine if new incoming data was written to an array you were performing operations on by first clearing WBSKT_BIN_STATUS_WRITING_ENDED, and then reading it afterwards to see if it was set because of an incoming binary websocket frame.

Finally, WBSKT_BIN_ARRAY defines the function int Wbskt_Bin_Activate_##NAME() (note, NAME is from the macro parameter list and is concatenated with "Wbskt_Bin_Activate_"). Incoming websocket binary frames have a string that define what variable the array data is destined for. Wbskt_Bin_Activate_##NAME() creates the mapping from the string to the array pointer. Until Wbskt_Bin_Activate_##NAME() is called on the array declared with WBSKT_BIN_ARRAY, it will not receive incoming websocket data. Wbskt_Bin_Activate_##NAME() returns a zero if there was no error. It returns a -1 if there was an error (for example, if the number of arrays activated exceeds WBSKT_BIN_MAX_ARRAYS). Wbskt_Bin_Activate_##NAME() must not be run before Wbskt_Bin_Init() has been run.

The example below shows how this macro is typically used

WBSKT_BIN_ARRAY( my_array_name, 20, float);
 
void transfer_service_init()
{
    Wbskt_Bin_Activate_my_array_name();
    // my_array_name is now a float with 20 elements that will
    // be written to if an incoming binary websocket frame is
    // destined for the variable "my_array_name"
}

Availability: Mosaic IDE+ revision 1636 or greater

WBSKT_BOOLEAN( NAME, INITIAL_VALUE );

A macro that defines a variable of the custom type boolean that may be updated via a received WebSocket event message generated by the JavaScript function MosaicPDQ.sendValue(). The name of the variable is specified in a raw token as the NAME argument, and the initialization value at boot is specified as the INITIAL_VALUE argument, which should be either TRUE or FALSE. Example:

WBSKT_BOOLEAN( beans_are_cooked, FALSE );

unsigned Wbskt_Boolean_LoadFrame( xaddr xbuffer, unsigned maxbytes,
                                  const char* elem_id, const char* attribute,
                                  boolean value );

Builds a JSON string suitable for interpretation by the MosaicPDQ JavaScript API, intended to be the payload of a WebSocket message, at a buffer that begins at the 32-bit extended address xbuffer in PDQ Board RAM. The JSON string will represent a value message to assign either JavaScript "true" or "false" based on the value argument to the attribute specified by the attribute argument of the HTML element with id matching the elem_id argument. If the JSON string is of length less than maxbytes, it will be NUL-terminated and the return value will be the length of the JSON string. If the resulting JSON string length equals or exceeds maxbytes, it will not be completely written to the buffer, it will not be NUL-terminated, and the return value will be equal to zero.

The paged RAM buffer provided by the EtherSmart Wildcard driver software at location specified by Ether_Outbuf() with size specified by Ether_Outbufsize() (see EtherSmart Wildcard driver glossary) is suitable for use in your application code for assembling outgoing WebSocket messages. The assembled message may be sent using the EtherSmart Wildcard driver function WS_Send().

This function may be used directly, along with the EtherSmart driver function WS_Send(), if you wish to perform error checking to ensure outgoing messages are sent. If error checking is not needed and the value is to be assigned to the innerHTML attribute of an element (i.e. its displayed content in most cases), you may instead use the simpler macro WBSKT_SEND_BOOLEAN().

WBSKT_CATCH( NAME );

A macro that performs runtime initialization of metadata for variables and functions to be updated or executed via received WebSocket messages. The WebSocket messaging library must have already been initialized with Wbskt_Init(), and the single argument NAME is a raw token specifying the name of a function defined with WBSKT_EVENT() or variable defined with WBSKT_BOOLEAN(), WBSKT_FLOAT(), or WBSKT_LONG(). For each such function or variable, runtime initialization of metadata must be performed by passing its name to WBSKT_CATCH().

unsigned Wbskt_ErrMsg_LoadFrame( xaddr xbuffer, unsigned maxbytes, Wbskt_Error_Type errnum );

Builds a JSON string suitable for interpretation by the MosaicPDQ JavaScript API, intended to be the payload of a WebSocket message, at a buffer that begins at the 32-bit extended address xbuffer in PDQ Board RAM. The JSON string will represent a readable error message associated with a return value of Wbskt_Incoming_Error() passed as errnum, to be passed to the JavaScript function MosaicPDQ.log() for display to the user. If the resulting JSON string is of length less than maxbytes, it will be NUL-terminated and the return value will be the length of the JSON string. If the resulting JSON string length equals or exceeds maxbytes, it will not be completely written to the buffer, it will not be NUL-terminated, and the return value will be equal to zero.

The paged RAM buffer provided by the EtherSmart Wildcard driver software at location specified by Ether_Outbuf() with size specified by Ether_Outbufsize() (see EtherSmart Wildcard driver glossary) is suitable for use in your application code for assembling outgoing WebSocket messages. The assembled message may be sent using the EtherSmart Wildcard driver function WS_Send().

This function may be used directly, along with the EtherSmart driver function WS_Send(), if you wish to perform error checking to ensure outgoing messages are sent. If error checking is not needed, you may instead use the simpler macro WBSKT_SEND_ERRMSG().

void Wbskt_ErrMsg_Puts( Wbskt_Error_Type errnum );

Prints to the default serial port a readable error message associated with a return value of Wbskt_Incoming_Error() passed as errnum, followed by a newline.

xaddr Wbskt_ErrMsg_Xaddr( Wbskt_Error_Type errnum );

Returns the 32-bit extended address of a readable error message associated with a return value of Wbskt_Incoming_Error() passed as errnum, stored in PDQ Board paged Flash as a NUL-terminated C string. The string may be copied into a common RAM buffer using FetchCstring() (see PDQ v6 C Glossary).

WBSKT_EVENT( NAME, ... );

A macro that defines a function that may be executed via a received WebSocket event message generated by the JavaScript function MosaicPDQ.sendEvent(). When defining a function that will be callable with WebSocket messages, WBSKT_EVENT() is used in place of the normal C function signature. The first argument to the macro is the name of the function, and subsequent arguments specify function arguments that must be pointers of type long*, float*, boolean*, or char*. One additional argument, the EtherSmart Wildcard module number, is also passed automatically to the defined function as the first argument, int modulenum. Mosaic's WebSocket message handling library passes all arguments to functions defined with WBSKT_EVENT() as pointers, and such functions may accept up to 14 arguments. For example, the following definition:

WBSKT_EVENT( bean_label_create, long* can_count, char* brand )
{
    ...
}

defines a WebSocket-callable function with the following signature (you need not enter the function definition as shown below; rather, this example shows the equivalent function definition created by the WBSKT_EVENT() macro used as shown above):

void bean_label_create( int modulenum, long* can_count, char* brand )
{
    ...
}

Once a function is defined with WBSKT_EVENT(), reception of event messages for the function must be initialized at runtime with WBSKT_CATCH() before event messages may be received and processed.

unsigned Wbskt_Event_LoadFrame( xaddr xbuffer, unsigned maxbytes,
                                const char* event_name, const char* event_params );

Builds a JSON string suitable for interpretation by the MosaicPDQ JavaScript API, intended to be the payload of a WebSocket message, at a buffer that begins at the 32-bit extended address xbuffer in PDQ Board RAM. The JSON string will represent an event message to execute a JavaScript function with name equal to the C string event_name using an argument list specified as a JavaScript array literal in the C string event_params. It is the responsibility of the application programmer to create a JavaScript array literal containing arguments to be passed to the JavaScript function, i.e. using sniprintf() and the LOADED_STRING buffer (see PDQ v6 C Glossary). The JavaScript array literal is bounded by opening and closing square brackets, containing a comma-separated list of JavaScript literals representing the values to be passed to the function. The array is not directly passed to the specified function, but rather is used with the apply() method of the function so that the contents of the array are passed as the function arguments.

If the resulting JSON string representing the entire message is of length less than maxbytes, it will be NUL-terminated and the return value will be the length of the JSON string. If the resulting JSON string length equals or exceeds maxbytes, it will not be completely written to the buffer, it will not be NUL-terminated, and the return value will be equal to zero.

The paged RAM buffer provided by the EtherSmart Wildcard driver software at location specified by Ether_Outbuf() with size specified by Ether_Outbufsize() (see EtherSmart Wildcard driver glossary) is suitable for use in your application code for assembling outgoing WebSocket messages. The assembled message may be sent using the EtherSmart Wildcard driver function WS_Send().

This function may be used directly, along with the EtherSmart driver function WS_Send(), if you wish to perform error checking to ensure outgoing messages are sent. If error checking is not needed and the value is to be assigned to the innerHTML attribute of an element (i.e. its displayed content in most cases), you may instead use the simpler macro WBSKT_SEND_EVENT().

WBSKT_FLOAT( NAME, INITIAL_VALUE );

A macro that defines a variable of type float (32-bit IEEE 754 floating point) that may be updated via a received WebSocket event message generated by the JavaScript function MosaicPDQ.sendValue(). The name of the variable is specified in a raw token as the NAME argument, and the initialization value at boot is specified as the INITIAL_VALUE argument, which should be a floating point literal. Example:

WBSKT_FLOAT( bean_velocity, 0.0f );

unsigned Wbskt_Float_LoadFrame( xaddr xbuffer, unsigned maxbytes,
                                const char* elem_id, const char* attribute,
                                float value );

Builds a JSON string suitable for interpretation by the MosaicPDQ JavaScript API, intended to be the payload of a WebSocket message, at a buffer that begins at the 32-bit extended address xbuffer in PDQ Board RAM. The JSON string will represent a value message to assign a JavaScript number equal to the floating-point value argument to the attribute specified by the attribute argument of the HTML element with id matching the elem_id argument. If the JSON string is of length less than maxbytes, it will be NUL-terminated and the return value will be the length of the JSON string. If the resulting JSON string length equals or exceeds maxbytes, it will not be completely written to the buffer, it will not be NUL-terminated, and the return value will be equal to zero.

The paged RAM buffer provided by the EtherSmart Wildcard driver software at location specified by Ether_Outbuf() with size specified by Ether_Outbufsize() (see EtherSmart Wildcard driver glossary) is suitable for use in your application code for assembling outgoing WebSocket messages. The assembled message may be sent using the EtherSmart Wildcard driver function WS_Send().

This function may be used directly, along with the EtherSmart driver function WS_Send(), if you wish to perform error checking to ensure outgoing messages are sent. If error checking is not needed and the value is to be assigned to the innerHTML attribute of an element (i.e. its displayed content in most cases), you may instead use the simpler macro WBSKT_SEND_FLOAT().

void Wbskt_Handle_Bin_Frame( xaddr ethersmart_inbuf, int modulenum );

This function is part of the binary extension to the websocket driver. This is a handler function for incoming websocket binary frames. It assumes that ethersmart_inbuf is the 32-bit extended address of a websocket binary frame sent from the "MosaicPDQ" JavaScript library. Parses the incoming frame and attempts to copy the array data to the variable specified within the frame. Array variables must be declared and activated using the WBSKT_BIN_ARRAY macro and resulting Wbskt_Bin_Activate_##NAME function. Errors are retrievable with Wbskt_Incoming_Error. Wbskt_Init() must have been already called before adding this handler (Wbskt_Init sets up the websocket error system). Typical usage shown below

#include <mosaic\allqed.h>
#include <wwifi.h>
#include <websocket.h>
 
void websocket_bin_handler( int modulenum)
{
    xaddr inbuf = HTTP_Inbuf( modulenum );
    Wbskt_Handle_Bin_Frame( inbuf, modulenum );
}
 
int main()
{
    Ether_C_Task_Setup( E_MODULENUM);
    IP_Set_Defaults();
 
    Wbskt_Init( FALSE );
    Wbskt_Bin_Init();
 
    WS_Add_Bin_Handler( COMMON_XADDR( websocket_bin_handler), E_MODULENUM);
    //Wbskt_Handle_Bin_Frame will now be called on incoming binary websocket frames.
 
    return 0;
}

Availability: Mosaic IDE+ revision 1636 or greater

void Wbskt_Handle_Frame( xaddr ethersmart_inbuf, int modulenum );

Assumes that ethersmart_inbuf is the 32-bit extended address of a Forth counted long string representing a received WebSocket message, meaning that the first two bytes at location ethersmart_inbuf specify the length of a WebSocket message appearing thereafter in PDQ Board paged memory. Copies the Forth counted long string at ethersmart_inbuf to an internal buffer in the WebSocket messaging library, and also copies to an internal variable the modulenum indicating the EtherSmart Wildcard module number at which the message was received. Assuming the WebSocket service task has been started with Wbskt_Init(), the received message will then be parsed and executed by the WebSocket service task. Generally this function is called within a WebSocket handler function by the EtherSmart Wildcard driver software running in the EtherSmart task.

Wbskt_Error_Type Wbskt_Incoming_Error( int modulenum );

Returns the last error that occurred on reception of a WebSocket message from the EtherSmart Wildcard with module number modulenum, and clears the internal variable holding incoming message errors. The return value is an enumerated type and may be passed to Wbskt_ErrMsg_Xaddr(), Wbskt_ErrMsg_Puts(), and Wbskt_ErrMsg_LoadFrame(). If no incoming errors have occurred, returns zero. All codes indicating errors evaluate to true in boolean tests.

void Wbskt_Init( unsigned char blocking_errors );

Must be called before using any other WebSocket messaging library functionality. Allocates memory and initializes data structures used internally by the WebSocket messaging library, then builds and activates the WebSocket servicing task to parse and execute incoming WebSocket messages. In most cases blocking_errors should be equal to FALSE (zero). If blocking_errors is non-zero, an error condition that occurs in the WebSocket task when another error condition is waiting to be read will cause the WebSocket servicing task to hang until Wbskt_Incoming_Error() is called to read the previous error condition. If you are debugging your application and wish to ensure that you see the first error condition that occurs before it is overwritten by subsequent errors, set blocking_errors equal to TRUE. In a final version of your application, blocking_errors should be equal to FALSE.

WBSKT_LONG( NAME, INITIAL_VALUE );

A macro that defines a variable of type long (32-bit integer) that may be updated via a received WebSocket event message generated by the JavaScript function MosaicPDQ.sendValue(). The name of the variable is specified in a raw token as the NAME argument, and the initialization value at boot is specified as the INITIAL_VALUE argument, which should be an integer literal. Example:

WBSKT_LONG( bean_count, 42 );

unsigned Wbskt_Long_LoadFrame( xaddr xbuffer, unsigned maxbytes,
                               const char* elem_id, const char* attribute,
                               long value );

Builds a JSON string suitable for interpretation by the MosaicPDQ JavaScript API, intended to be the payload of a WebSocket message, at a buffer that begins at the 32-bit extended address xbuffer in PDQ Board RAM. The JSON string will represent a value message to assign a JavaScript number equal to the 32-bit integer value argument to the attribute specified by the attribute argument of the HTML element with id matching the elem_id argument. If the JSON string is of length less than maxbytes, it will be NUL-terminated and the return value will be the length of the JSON string. If the resulting JSON string length equals or exceeds maxbytes, it will not be completely written to the buffer, it will not be NUL-terminated, and the return value will be equal to zero.

The paged RAM buffer provided by the EtherSmart Wildcard driver software at location specified by Ether_Outbuf() with size specified by Ether_Outbufsize() (see EtherSmart Wildcard driver glossary) is suitable for use in your application code for assembling outgoing WebSocket messages. The assembled message may be sent using the EtherSmart Wildcard driver function WS_Send().

This function may be used directly, along with the EtherSmart driver function WS_Send(), if you wish to perform error checking to ensure outgoing messages are sent. If error checking is not needed and the value is to be assigned to the innerHTML attribute of an element (i.e. its displayed content in most cases), you may instead use the simpler macro WBSKT_SEND_LONG().

WBSKT_SEND_BOOLEAN( ELEM_ID, VALUE, MODULENUM );

If a WebSocket connection has been opened by a browser to the EtherSmart Wildcard with jumper-selected module number MODULENUM, sends a JSON-formatted value message over the WebSocket connection to the browser to be displayed in an HTML element. The MosaicPDQ JavaScript library will assign a JavaScript true or false value based on whether the argument VALUE evaluates to true or false in C, to the innerHTML attribute of the element with id equal to ELEM_ID. If a WebSocket connection is not currently open to the specified Wildcard, does nothing.

Assumes that the EtherSmart Wildcard driver software is available, i.e. that the source code includes #include <wwifi.h> . Calls the EtherSmart Wildcard driver functions WS_Is_Open(), Ether_Outbuf(), Ether_Outbufsize(), and WS_Send(). Performs no error checking. For sending an outgoing message with error checking, see the underlying function Wbskt_Boolean_LoadFrame().

WBSKT_SEND_ERRMSG( ERRNUM, MODULENUM );

If a WebSocket connection has been opened by a browser to the EtherSmart Wildcard with jumper-selected module number MODULENUM, sends a JSON-formatted error message over the WebSocket connection to the browser to be passed to the function MosaicPDQ.log() for display to the user. The ERRNUM argument is a return value from the function Wbskt_Incoming_Error(), and the readable error message to be displayed to the user will be that at the location returned by Wbskt_ErrMsg_Xaddr(). If a WebSocket connection is not currently open to the specified Wildcard, does nothing.

Assumes that the EtherSmart Wildcard driver software is available, i.e. that the source code includes #include <wwifi.h> . Calls the EtherSmart Wildcard driver functions WS_Is_Open(), Ether_Outbuf(), Ether_Outbufsize(), and WS_Send(). Performs no error checking. For sending an outgoing message with error checking, see the underlying function Wbskt_ErrMsg_LoadFrame().

WBSKT_SEND_EVENT( NAME, PARAMS, MODULENUM );

If a WebSocket connection has been opened by a browser to the EtherSmart Wildcard with jumper-selected module number MODULENUM, sends a JSON-formatted event message over the WebSocket connection to the browser. The MosaicPDQ JavaScript library will execute a JavaScript function defined in the global context with name NAME, and pass it arguments specified as a JavaScript array literal in the NUL-terminated C string PARAMS. See Wbskt_Event_LoadFrame() for details on constructing a JavaScript array literal containing the function arguments. If a WebSocket connection is not currently open to the specified Wildcard, does nothing.

Assumes that the EtherSmart Wildcard driver software is available, i.e. that the source code includes #include <wwifi.h> . Calls the EtherSmart Wildcard driver functions WS_Is_Open(), Ether_Outbuf(), Ether_Outbufsize(), and WS_Send(). Performs no error checking. For sending an outgoing message with error checking, see the underlying function Wbskt_Event_LoadFrame().

WBSKT_SEND_FLOAT( ELEM_ID, VALUE, MODULENUM );

If a WebSocket connection has been opened by a browser to the EtherSmart Wildcard with jumper-selected module number MODULENUM, sends a JSON-formatted value message over the WebSocket connection to the browser to be displayed in an HTML element. The MosaicPDQ JavaScript library will assign a JavaScript number value based on the 32-bit floating point argument VALUE, to the innerHTML attribute of the element with id equal to ELEM_ID. If a WebSocket connection is not currently open to the specified Wildcard, does nothing.

Assumes that the EtherSmart Wildcard driver software is available, i.e. that the source code includes #include <wwifi.h> . Calls the EtherSmart Wildcard driver functions WS_Is_Open(), Ether_Outbuf(), Ether_Outbufsize(), and WS_Send(). Performs no error checking. For sending an outgoing message with error checking, see the underlying function Wbskt_Float_LoadFrame().

WBSKT_SEND_HEARTBEAT( MODULENUM );

If a WebSocket connection has been opened by a browser to the EtherSmart Wildcard with jumper-selected module number MODULENUM, sends a JSON-formatted heartbeat message over the WebSocket connection to the browser. The message is of a format that the MosaicPDQ JavaScript library expects to receive periodically. If a heartbeat message is not received for five seconds, the WebSocket connection is closed and re-opened. It is recommended that your application call WBSKT_SEND_HEARTBEAT() once per second. If a WebSocket connection is not currently open to the specified Wildcard, does nothing.

Assumes that the EtherSmart Wildcard driver software is available, i.e. that the source code includes #include <wwifi.h> . Calls the EtherSmart Wildcard driver functions WS_Is_Open() and WS_Send().

WBSKT_SEND_LONG( ELEM_ID, VALUE, MODULENUM );

If a WebSocket connection has been opened by a browser to the EtherSmart Wildcard with jumper-selected module number MODULENUM, sends a JSON-formatted value message over the WebSocket connection to the browser to be displayed in an HTML element. The MosaicPDQ JavaScript library will assign a JavaScript number value based on the 32-bit integer argument VALUE, to the innerHTML attribute of the element with id equal to ELEM_ID. If a WebSocket connection is not currently open to the specified Wildcard, does nothing.

Assumes that the EtherSmart Wildcard driver software is available, i.e. that the source code includes #include <wwifi.h> . Calls the EtherSmart Wildcard driver functions WS_Is_Open(), Ether_Outbuf(), Ether_Outbufsize(), and WS_Send(). Performs no error checking. For sending an outgoing message with error checking, see the underlying function Wbskt_Long_LoadFrame().

WBSKT_SEND_STRING( ELEM_ID, VALUE, MODULENUM );

If a WebSocket connection has been opened by a browser to the EtherSmart Wildcard with jumper-selected module number MODULENUM, sends a JSON-formatted value message over the WebSocket connection to the browser to be displayed in an HTML element. The MosaicPDQ JavaScript library will assign the string provided by the NUL-terminated C string VALUE, to the innerHTML attribute of the element with id equal to ELEM_ID. If a WebSocket connection is not currently open to the specified Wildcard, does nothing.

Assumes that the EtherSmart Wildcard driver software is available, i.e. that the source code includes #include <wwifi.h> . Calls the EtherSmart Wildcard driver functions WS_Is_Open(), Ether_Outbuf(), Ether_Outbufsize(), and WS_Send(). Performs no error checking. For sending an outgoing message with error checking, see the underlying function Wbskt_String_LoadFrame().

void Wbskt_Service_Loop();

Generally not called directly by the programmer. This is the task activation routine that runs in the WebSocket service task, started by Wbskt_Init(). Continually checks for messages that have been received with Wbskt_Handle_Frame(), generally in a handler function running in the EtherSmart task. When a message has been received, parses and executes it - i.e. updates a global variable based on a value message or executes a function based on an event message.

unsigned Wbskt_String_LoadFrame( xaddr xbuffer, unsigned maxbytes,
                                const char* elem_id, const char* attribute,
                                const char* value );

Builds a JSON string suitable for interpretation by the MosaicPDQ JavaScript API, intended to be the payload of a WebSocket message, at a buffer that begins at the 32-bit extended address xbuffer in PDQ Board RAM. The JSON string will represent a value message to assign a JavaScript string equal to the NUL-terminated C string value argument to the attribute specified by the attribute argument of the HTML element with id matching the elem_id argument. If the resulting JSON string representing the message is of length less than maxbytes, it will be NUL-terminated and the return value will be the length of the JSON string. If the resulting JSON string length equals or exceeds maxbytes, it will not be completely written to the buffer, it will not be NUL-terminated, and the return value will be equal to zero.

The paged RAM buffer provided by the EtherSmart Wildcard driver software at location specified by Ether_Outbuf() with size specified by Ether_Outbufsize() (see EtherSmart Wildcard driver glossary) is suitable for use in your application code for assembling outgoing WebSocket messages. The assembled message may be sent using the EtherSmart Wildcard driver function WS_Send().

This function may be used directly, along with the EtherSmart driver function WS_Send(), if you wish to perform error checking to ensure outgoing messages are sent. If error checking is not needed and the value is to be assigned to the innerHTML attribute of an element (i.e. its displayed content in most cases), you may instead use the simpler macro WBSKT_SEND_STRING().