The EtherSmart Wildcard Glossary

Glossary of EtherSmart Wildcard Driver Functions

C: void Cat (xaddr xcountedLString, uint umaxChars, xaddr xstringToAdd, int countToAdd, uint eol)

4th:Cat ( xcountedLString\umaxChars\xstringToAdd\countToAdd\eol -- )

Concatenates (appends) a string specified by xstringToAdd and countToAdd, plus a specified 1- or 2-byte eol (end of line) sequence and a terminating null byte (not included in the count), to a string in a long buffer specified by xcountedLString, and increments the buffer count that is stored in the first two bytes of xcountedLString to reflect the updated buffer contents. This routine clamps the maximum number of bytes in the destination buffer at xcountedLString to umaxChars; this value does not include the 2-byte count stored at the start of the buffer. (Recall that a longstring buffer comprises a 2-byte count followed by the buffer contents). The allocated buffer size in RAM should be at least 3 bytes larger than the specified umaxChars to allow for the 2-byte count and the terminating null byte. While umaxChars can be as large as 65532 bytes, the countToAdd string length must be a positive integer less than or equal to 32,767 bytes. The eol parameter can contain 1 or 2 bytes; typical values are 0x0D (carriage return), 0x0A (linefeed), 0x0D0A (carriage return/linefeed), or 0x00 (null byte). If the eol parameter = -1, no eol bytes are stored in the string by this function. If the most significant (ms) byte of the eol parameter is non-zero, two bytes are stored in the buffer after the appended string: first the msbyte of eol, then the lsbyte of eol. This function provides a way for both forth and C programs to build a long string in memory.

NOTE: Remember to zero the first 2 bytes (16-bit count) of the xcountedLString buffer before the first call to this routine; this initializes the counted lbuffer to its starting size of zero.

C: uchar E_ASCII_Key ( void )

4th: E_ASCII_Key ( -- char )

For the EtherSmart module whose value is stored in the ether_revector_module variable, waits for and returns the next pending input character. Unlike E_Key, this function ignores any incoming character that has its most significant bit set, or that is non-printable. It ignores “control” characters with values less than 0x20, except that ascii 0x07 through 0x0A (BEL, BS, TAB, LF) or 0x0D (CR) are accepted. This function is useful for ascii-only file transfers, but of course must not be used for binary transfers. See Ether_Serial_Revector and Ether_Monitor.

Implementation detail: Fetches the contents of ether_revector_module and calls Ether_ASCII_Key.

C: int E_Ask_Key ( void )

4th: E_Ask_Key ( -- flag )

For the EtherSmart module whose value is stored in the ether_revector_module variable, returns a flag that is true if the 64-byte UART input FIFO (First In/First Out buffer) on the Wildcard contains at least one character, and is false there are no characters in the input FIFO. See Ether_Serial_Revector and Ether_Monitor.

Implementation detail: Fetches the contents of ether_revector_module and calls Ether_Ask_Key.

C: void E_Emit ( uchar character )

4th: E_Emit ( character -- )

Sends the specified character for transmission to the Ethernet to the EtherSmart Wildcard module whose value is stored in the ether_revector_module variable. This function waits until the UART on the Wildcard can accept a character, then sends it. This function has the same stack picture (parameter list) as the standard Emit output function used by the operating system, and so can be used to revector serial I/O via the EtherSmart Wildcard. See Ether_Serial_Revector and Ether_Monitor.

Implementation detail: Fetches the contents of ether_revector_module and calls Ether_Emit.

C: uchar E_Key ( void )

4th: E_Key ( -- flag )

For the EtherSmart module whose value is stored in the ether_revector_module variable, waits for and returns the next pending input character. See Ether_Serial_Revector and Ether_Monitor.

Implementation detail: Fetches the contents of ether_revector_module and calls Ether_Key.

C: void Ether_Add_Chars ( xaddr xlbuffer, uint maxbytes, uint maxlines, char eol,

int discard_alt_eol, int discard_msbit_set, uint timeout_msec, int modulenum )

4th: Ether_Add_Chars ( xlbuf\maxchars\maxlines\eol\discard.alt.eol\no.msbitset\timeout\module--)

Stores the specified input parameters into the ether_info struct and SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). Requests and stores incoming ASCII data from the specified EtherSmart modulenum. The data is appended to xlbuffer, a counted buffer whose byte count is stored in the first 2 bytes of the buffer, and the count is incremented by the number of appended bytes. The xlbuffer parameter is a 32-bit extended address that holds the 16-bit buffer count followed by the buffer data. The appended data is stored starting at xlbuf+2+prior_count, where prior_count is the 16-bit contents at xlbuf upon entry into this routine. The data input operation stops if the amount of data in the specified buffer (including any prior data, but not including the 2-byte count) exceeds the specified maxbytes parameter. A maximum of maxlines are accepted, where a “line” is a data sequence ending in the specified eol (end of line) character. If the maxlines input parameter = -1, then the line limit is ignored. If maxlines = 0, then all except the last incoming line are discarded, and only the last line is added to the buffer, excluding the final eol character which is discarded and not added to the buffer. The eol parameter is a single character that specifies End Of Line. Typical values are ‘CR’ = 0x0D or ‘LF’ = 0x0A. Dual-character eol sequences such as CRLF are not allowed. If eol_char = ‘LF’, we define the “alternate eol” is a ‘CR’. For all other eol chars (including a ‘CR’), the “alternate eol” is a ‘LF’. If the discard_alt_eol flag parameter is true, the alternate to the specified eol character is discarded/ignored by this routine. If the flag is false, the alternate eol char does not get special treatment, and is stored in the buffer like any other character. If the no_msbitset flag parameter is true, then any characters having its most significant (ms) bit set (bit7, bitmask = 0x80) is discarded and is not stored in the buffer. This is useful, for example, if the incoming data is sent by a telnet application; some tty configuration data is transmitted that can be filtered out by discarding characters with their ms-bits set. This function exits within the specified timeout_msec whether or not the maximum number of bytes or lines have been accepted. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and numbytes_appended in the remaining 2 bytes is placed in the ether_response mailbox. To test for a buffer overrun, fetch the 2-byte count from xlbuffer and test whether it is greater than or equal to the allowed maxbytes. The specified maxbytes must be less than or equal to 65533 so that the maximum buffersize including count fits in a 16-bit number. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response. This routine must not be used to input binary (non-ascii) data; see also Ether_Get_Data and Ether_Add_Data.

C: void Ether_Add_Data ( xaddr xlbuffer, uint maxbytes, uint timeout_msec, int modulenum )

4th: Ether_Add_Data ( xlbuffer\maxbytes\timeout_msec\modulenum -- )

C: void Ether_Add_Line ( xaddr xlbuffer, uint maxbytes, char eol, int discard_alt_eol,

int discard_msbit_set, uint timeout_msec, int modulenum )

4th: Ether_Add_Line ( xlbuffer\maxchars\eol\discard.alt.eol?\no.msbitset?\timeout_msec\module--)

Calls Ether_Add_Chars, passing 1 as the maxlines parameter to input a maximum of one line of text with the specified eol (end of line) character. See Ether_Add_Chars.

C: uchar Ether_ASCII_Key ( int modulenum )

4th: Ether_ASCII_Key ( modulenum -- char )

For the specified EtherSmart module, waits for and returns the next pending input character. Unlike Ether_Key, this function ignores any incoming character that has its most significant bit set, or that is non-printable. It ignores “control” characters with values less than 0x20, except that ascii 0x07 through 0x0A (BEL, BS, TAB, LF) or 0x0D (CR) are accepted. This function is useful for ascii-only file transfers, but of course must not be used for binary transfers. See Ether_ Key, Ether_Emit, and E_Ascii_Key.

C: int Ether_Ask_Emit ( int modulenum )

4th: Ether_Ask_Emit ( modulenum -- ok_to_send? )

For the specified EtherSmart module, returns a flag that is true if the 64-byte UART output FIFO (First In/First Out buffer) on the Wildcard is ready to accept a character, and is false otherwise. See Ether_Emit, Ether_Ask_Key, and E_Ask_Emit.

C: int Ether_Ask_Key ( int modulenum )

4th: Ether_Ask_Key ( modulenum -- char_available? )

For the specified EtherSmart module, returns a flag that is true if the 64-byte UART input FIFO (First In/First Out buffer) on the Wildcard contains at least one character, and is false there are no characters in the input FIFO. See Ether_Emit, Ether_Key, and E_Ask_Key.

C: ulong Ether_Await_Response ( int modulenum )

4th: Ether_Await_Response ( modulenum -- d.mailbox_contents )

This blocking function waits until the ether_response mailbox contains a non-zero value, and returns the value. Use this function to wait until a just-issued command to the Ethernet task has completed and generated a response in the ether_response mailbox for the specified EtherSmart modulenum. The ether_response mailbox is declared using the Ether_Info_Init function and its callers (Ether_Init, Ether_Setup, Ether_Setup_Default, etc.) Typically the least significant 16-bits in the mailbox is either an error code (also stored at Ether_Error) or a number of bytes sent or received. The most significant byte in the mailbox is the command_id, and the remaining byte is the modulenum. For the recommended non-blocking version and additional details, see Ether_Check_Response.

C: ETHER_BUFSIZE_DEFAULT

4th: ETHER_BUFSIZE_DEFAULT

A 16-bit constant that returns the value 510. This constant is used by Ether_Setup to specify the size of the Ether_Outbuf and Ether_Inbuf buffers, and is returned by Ether_Inbufsize and Ether_Outbufsize after Ether_Setup is executed. Each buffer is allocated as 512 bytes, comprising a 2-byte count stored in the first 2 bytes of the buffer, followed by the 510 maximum bytes of data in the buffer.

C: int Ether_Check_GUI ( int modulenum )

4th: Ether_Check_GUI ( modulenum -- gui_handler_called? )

This non-blocking function checks the contents of the ether_gui_message mailbox without pausing. If an application supports a web-based “remote front panel” for an instrument that contains a touchscreen and graphics display, this function must be called on each pass through the application task’s program loop. If the ether_gui_message mailbox is empty (i.e., if its contents = zero indicating that there is no pending GUI web request), then this routine returns a 16-bit zero flag. If the mailbox is not empty (i.e., if its contents = the xcfa and modulenum packed into a 32-bit parameter indicating that there is a pending GUI web request), then this routine executes the specified GUI handler and returns a 16-bit true (-1) flag to indicate that the handler was called. In this case, the Ethernet task automatically closes the HTTP connection after the handler has executed. No additional mail to the application task is generated by the execution of the handler function. The handler function for the web request is posted using the HTTP_Add_GUI_Handler function; see its glossary entry for important details about the handler function and URL web address. A typical application program that supports a web-based “remote front panel” will call this routine and Ether_Check_Response and Ether_Connect_Status on each pass through the application program loop to manage the Ethernet activities.

Usage Notes: A GUI handler is used to implement a web-based “remote front panel” for an instrument that contains a touchscreen and graphics display. When a user clicks on a screen image (typically the same image that is present on the graphics display) presented in a browser window, a series of events is launched that result in the GUI toolkit processing the input as if a touch on the touchscreen had occurred, calling the associated GUI action function, and updating the screen image both on the instrument an on the remote browser screen. A GUI handler is different than a standard webservice handler. A standard non-GUI webservice handler executes automatically without any intervention from the user’s application task, and is dispatched by the Ethernet task running the Ether_Service_Loop routine. A GUI handler, on the other hand, requires an interaction with the GUI Toolkit, and, for task synchronization reasons, must be dispatched from the user’s application task. The HTTP_Add_GUI_Handler function posts the handler function and the associated URL to the autoserve array, and marks the function as a GUI Handler so that it will be dispatched via the application task from this Ether_Check_GUI routine. In the HTTP GUI handler function, the HTTP_Imagemap function (see its glossary entry) should be called to extract and return the X and Y coordinates from the query field. Then the Simulated_Touch_To_Image function (defined in the special GUI Toolkit section of this glossary document) can be invoked to simulate the touch at the specified screen coordinates, draw the press and release graphics, activate the screen button’s press handler, and, if the screen image changed, reload the screen image buffer with the updated screen bitmap image. Then HTTP_GUI_Send_2Buffers can be used to send the HTTP header and HTML text (in the first buffer) and graphics image (in the second buffer) to the browser to complete the handler’s actions.

C: ulong Ether_Check_Response ( int modulenum )

4th: Ether_Check_Response ( modulenum -- d.mailbox_contents )

This non-blocking function checks the contents of the ether_response mailbox for the specified module without waiting or pausing. The user’s main application program can call this routine repeatedly as part of the main program loop to keep the response mailbox clear. If mail is pending from the Ethernet control task running the Ether_Service_Loop, this routine returns the mailbox contents; this occurs when the most recently-issued command has generated a response in the ether_response mailbox. If the mailbox is empty, the returned value is a 32-bit zero. Use this function to periodically check the response in the ether_response mailbox whose address is stored in the ether_info struct of the specified wildcard module as set by the Ether_Info_Init, Ether_Init, and Ether_Setup routines. Typically the least significant 16-bits in the mailbox is either an error code (also stored at Ether_Error) or a number of bytes sent or received. The most significant byte in the mailbox is the command_id, and the remaining byte is the modulenum. A typical application program calls this routine, and Ether_Connect_Status and/or Ether_Passive_Non_Web_Connection on each pass through the program loop to manage the Ethernet activities performed by the task running the Ether_Service_Loop. Applications that support the web-based “remote front panel” would also call Ether_Check_GUI. Note that the ether_response mailbox is not actively “cleared” (emptied) unless this routine returns a non-zero result, indicating that an incoming message has been received. For a blocking version, see Ether_Await_Response.

C: ulong ether_command

4th: ether_ command ( -- xaddr )

A mailbox in common RAM that conveys a 32-bit value from the user’s application task to the Ethernet control task. The programmer never has to explicitly access this mailbox, as it is zeroed by the Ether_Init and/or Ether_Setup routine and managed by the Ethernet driver functions. Each command function writes a command_id byte and the relevant modulenum into the msword, and 0 into the lsword of this mailbox. The Ether_Command_Manager routine called by Ether_Service_Loop receives the mailbox contents and dispatches the correct action function from the Ethernet task.

Note: This mailbox is typically not accessed directly. In C, this mailbox can be used as an lvalue or an rvalue, just like any C variable. In Forth, this variable has the standard behavior or returning the xaddress of its contents.

C: void Ether_Command_Manager ( int modulenum )

4th: Ether_Command_Manager ( modulenum -- )

This is the command processor, called by Ether_Service_Loop which is the task activation routine for the Ethernet control task. This routine is typically not called by the programmer. Does nothing if the ether_command mailbox is empty. If the ether_command mailbox is full and it contains the specified modulenum, this routine calls the routine corresponding to the command_id parameter, with the called function expecting its required parameters to be in the ether_info struct, as placed by the originating function invoked from the application program. Commands dispatched by this function include those originated by the following functions:

Ether_Get_Data Ether_Add_Data

Ether_Get_Chars Ether_Add_Chars

Ether_Send_Buffer Ether_Send_LBuffer

Ether_Send_2Buffers HTTP_GUI_Send_Buffer

HTTP_GUI_Send_LBuffer HTTP_GUI_Send_2Buffers

Ether_Connect Ether_Disconnect

Ether_Flush Ether_Flush_Nbytes

Ether_Ping_Request Ether_Ping_Report

Ether_IP_Info_Request Ether_IP_Info_Report

Ether_XPort_Defaults Ether_XPort_Update

Ether_Send_Email

See their glossary entries for details.

C: void Ether_Connect ( char ip1, char ip2, char ip3, char ip4, int port,

int timeout_msec, int modulenum )

4th: Ether_Connect ( ip1\ip2\ip3\ip4\port\timeout_msec\module -- )

C: int Ether_Connect_Status ( int modulenum )

4th: Ether_Connect_Status ( modulenum -- status )

Returns an integer representing the current connection status of the specified EtherSmart Wildcard as managed by the task running the Ether_Service_Loop. The returned values have the following meanings:

Value Meaning

0 Not connected.

1 Pending disconnect (disconnect failed, waiting to retry the disconnect)

2 Active connection initiated by us

3 Active connection that has been interrupted by a remote disconnect during a send

4 Passive connection initiated by remote, identified as non-HTTP

5 Passive non-HTTP connection interrupted by a remote disconnect during a send

6 Passive connection initiated by remote, identified as HTTP (GET was detected)

7 Passive HTTP connection interrupted by a remote disconnect during a send

8 Passive HTTP connection with web service completed, awaiting connection close

Web connections are typically transient, as they are closed by the webserver running on the Ethernet task after the user-specified handler corresponding to the requested URL has executed. Active connections (those initiated by the application program) must be maintained by the application program by calling routines to accept incoming data, send outgoing data, and close the connection at the appropriate time. Calling this Ether_Connect_Status routine enables the application task to detect incoming passive non-web connections from the remote so that the connection can be serviced by calling routines to accept incoming data, send outgoing data, and close the connection at the appropriate time. Even while an active or passive non-HTTP connection is open, this routine should be periodically called to detect if the remote has unexpectedly closed the connection. For a function that directly reports whether a passive non-web connection is active, see Ether_Passive_Non_Web_Connection. If Ether_Connect_Status indicates that a formerly open connection has closed, (for example, if the remote terminated the connection), it is recommended that you input any incoming chars using Ether_Get_Data or a related function, or call Ether_Flush to be sure you’ve cleaned up any incoming bytes so that they do not erroneously appear as the first bytes sent by the subsequent connection. If the returned status is one of the odd values 3, 5, or 7, it indicates that the remote either issued a RST (reset) packet, or simply closed the connection while we were attempting to send data to the remote. If the remote closed the connection, the connection status will automatically change to 0 (not connected). If, however, the remote reset the connection and immediately reconnected, further sends via Ether_Send_Buffer, Ether_Send_LBuffer, and Ether_Send_2Buffers will be ineffective until the connection status changes (for example, via the execution of Ether_Disconnect followed by Ether_Connect). This behavior prevents inadvertently sending data meant for one TCP/IP connection to another one.

C: void Ether_Connection_Manager ( int modulenum )

4th: Ether_Connection_Manager ( modulenum -- )

This is the connection status manager, called by Ether_Service_Loop (see its glossary entry) which is the task activation routine for the Ethernet control task (see Ether_Task_Setup). This routine is typically not called by the programmer. Checks and updates the connection status and corresponding flags in the ether_info struct, and detects and identifies passive incoming connections as HTTP- or non-HTTP connections. If the incoming connection is identified as an HTTP connection by virtue of a leading GET substring, and if the variable pointed to by HTTP_Enable_Ptr is non-zero, this routine calls HTTP_Server (which calls the user-specified handler function to serve out the web content) and closes the connection. If the connection identifies as non-HTTP, and if the variable pointed to by Ether_Tunnel_Enable_Ptr is non-zero, the connection status is set to PASSIVE_NON_WEB_CONNECTION, and it is up to the user’s application task repeatedly calling Ether_Connect_Status and/or Ether_Passive_Non_Web_Connection on each pass through the program loop to detect and service the incoming serial tunneling connection. The variables pointed to by HTTP_Enable_Ptr and Ether_Tunnel_Enable_Ptr are set to -1 (true) by Ether_Info_Init and its callers Ether_Init and Ether_Setup.

C: void Ether_DHCP_Name ( xaddr xname_string, int name_cnt, int modulenum )

4th: Ether_DHCP_Name ( xname_string\count\modulenum -- )

Writes the specified string specifier parameters into the ether_info struct for the specified module as the name used by DHCP (Dynamic Host Configuration Protocol). The xaddress xname_string is the 32-bit base address of the first character of the string, and count is the number of bytes in the string (clamped to a maximum of 8 bytes). Assuming that you have initialized the Ethernet task (see Ether_Task_Setup), you can instantiate the string into XPort flash after invoking this function by executing Ether_Update followed by Ether_Await_Response. Use of this string is optional. If you do not change the DHCP name from its default (as set by Ether_XPort_Defaults) and the XPort local IP is stored as its default value of 0.0.0.0, then the DHCP name defaults to Cxxxxxx, where xxxxx represents the last 6 digits of the MAC address shown on the label on the XPort. For example, if the MAC address is 00-20-4A-12-34-56, then the default DHCP name is C123456. Note that the DHCP name is not a nameservice name, and cannot in general be typed into a web browser’s address bar in place of the IP address. See the user guide for hints about how to refer to the EtherSmart Wildcard by name on the Local Area Network.

C: void Ether_Disconnect ( int modulenum )

4th: Ether_Disconnect ( modulenum -- )

SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). This function terminates the current connection by waiting 1 second, sending to the XPort the 3-byte escape sequence preamble +++, then waiting another second, then sending the ATH hang-up sequence followed by a carriage return. If the XPort is connected on entry into this routine and we successfully disconnect, or if the XPort is disconnected on entry into this routine, Ether_Connect_Status (see its glossary entry) is updated to return the disconnected state (0). If the remote computer disconnects or sends a RST (TCP/IP reset) packet during the disconnect process, this function aborts the sending of the escape sequence; this is dictated by hardware and firmware constraints in the Lantronix XPort. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and error flag in the remaining 2 bytes is placed in the ether_response mailbox; the error flag is also available using Ether_Error. The error flag is zero if the operation was successful, or nonzero if the XPort was still connected after sending the hang-up sequence; this can happen when we’ve sent a lot of chars to the XPort, as the XPort will have to send them all before disconnecting. Therefore, a non-zero error flag does not necessarily indicate that there is a problem, but if you want to ensure a disconnect, you can call this function again if a nonzero error flag is returned. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 2 seconds have elapsed, so please be patient. This routine does not flush the input FIFO (First In/First Out) buffers; see Ether_Disconnect_Flush for a routine that does flush the input buffers.

C: int Ether_Disconnect_During_Send ( int modulenum )

4th: Ether_Disconnect_During_Send ( modulenum -- flag )

Returns a true flag if a disconnect was detected while we were attempting to send data to the Ethernet. This routine is called within the data send routines associated with Ether_Send_Buffer, Ether_Send_LBbuffer, Ether_Send_2Buffers, HTTP_Send_Buffer, HTTP_Send_LBuffer, HTTP_Send_2Buffers, HTTP_GUI_Send_Buffer, HTTP_GUI_Send_LBuffer, and HTTP_GUI_Send_2Buffers. If a transient disconnect occurred (e.g., owing to a RST reset packet from the remote), further data transmission will be suppressed until the connection status changes (for example, via the execution of Ether_Disconnect followed by Ether_Connect). This behavior prevents inadvertently sending data meant for one TCP/IP connection to another one. See Ether_Connect_Status.

Implementation detail: This routine’s out is a result of monitoring of the delta_dcd hardware bit on the UART chip of the EtherSmart Wildcard.

C: void Ether_Disconnect_Flush ( int modulenum )

4th: Ether_Disconnect_Flush ( modulenum -- )

SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). This function terminates the current connection by waiting 1 second, sending to the XPort the 3-byte escape sequence preamble +++, then waiting another second, then sending the ATH hang-up sequence followed by a carriage return. If the XPort is connected on entry into this routine and we successfully disconnect, or if the XPort is disconnected on entry into this routine, Ether_Connect_Status (see its glossary entry) is updated to return the disconnected state (0). If the remote computer disconnects or sends a RST (TCP/IP reset) packet during the disconnect process, this function aborts the sending of the escape sequence; this is dictated by hardware and firmware constraints in the Lantronix XPort. During the two 1-second delays while sending the hang-up escape sequence, this routine reads and discards (flushes) any incoming characters from the input FIFO (First In/First Out) buffers on the EtherSmart Wildcard, so be sure you’ve already retrieved any expected incoming bytes. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and error flag in the remaining 2 bytes is placed in the ether_response mailbox; the error flag is also available using Ether_Error. The error flag is zero if the operation was successful, or nonzero if the XPort was still connected after sending the hang-up sequence; this can happen when we’ve sent a lot of chars to the XPort, as the XPort will have to send them all before disconnecting. Therefore, a non-zero error flag does not necessarily indicate that there is a problem, but if you want to ensure a disconnect, you can call this function again if a nonzero error flag is returned. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 2 seconds have elapsed, so please be patient. This routine flushes the input FIFO (First In/First Out) buffers; see Ether_Disconnect for a routine that does not flush the input buffers.

C: void Ether_Emit ( uchar character, int modulenum )

4th: Ether_Emit ( character\modulenum -- )

Sends the specified character to the specified EtherSmart Wildcard module for transmission to the Ethernet. This function waits until the UART on the Wildcard can accept a character, then sends it. See Ether_Ask_Emit, Ether_Key, and E_Emit.

C: int Ether_Encryption ( ulong key1, ulong key2, ulong key3, ulong key4, ulong key5,

ulong key6, ulong key7, ulong key8, int modulenum )

4th: Ether_Encryption

( d_key1\d_key2\d_key3\d_key4\d_key5\d_key6\d_key7\d_key8\module--error)

Installs 256 bit AES Rijndael encryption with the specified set of eight 32-bit keys key1 (most significant) through key8 (least significant) on the specified EtherSmart module. Returns 0 if successful, or returns a nonzero flag if the operation was not successful. To undo the effect of this command and return to non-encrypted operation, make sure that the Ethernet task is running (see Ether_Task_Setup) and execute Ether_XPort_Defaults (see its glossary entry). Rijndaell is the block cipher algorithm chosen by the National Institute of Science and Technology (NIST) as the Advanced Encryption Standard (AES) to be used by the US government. Configuring two or more XPort devices with the same keys and key length allows them to communicate with one another, while preventing anyone who does not know the encryption key from deciphering the network data.

To use: After a restart, initialize the EtherSmart Wildcard using Ether_Setup or one if its calling functions, and then invoke Ether_Encryption, passing it the 8 32-bit encryption keys in order from left to right. (Forth users should remember to type DIN before each 32-bit key.) Make sure there are no active connections during the execution of this function, as they will be interfered with when monitor mode is entered. Double check the key values, as there is no way to read them back after they are set.

Implementation detail: This routine acts directly on the XPort, not via the ether task, and so should be executed when there is no network activity being managed by the Ethernet task. This function enters monitor mode, moves the default block1 contents to Ether_Outbuf, writes the encryption keys and security flags to enable 256-bit AES encryption, writes block1 to the XPort, then executes the monitor mode RS reset command to instantiate the new values into the XPort flash memory. The entire operation takes approximately 13 seconds, so please be patient.

Encryption notes: An alternate way to configure the encryption settings is to go into setup mode by connecting to port 9999 using the “raw” data transfer mode of a free Ethernet terminal program such as Putty, and hitting enter within 3 seconds. Then choose option 6 (security), then follow the prompts to enable encryption, choose key length, and change/enter a key. Providing the same key to several XPorts on a network enables them to exchange encrypted communications among themselves.

EXPort agreement: This and other devices that implement encryption cannot be eXPorted or re-eXPorted to a national resident of Cuba, Iran, North Korea, Sudan, Syria or any other country to which the United States has embargoed goods; see the Lantronix documentation and website for details.

C: uint Ether_Error ( int modulenum )

4th: Ether_Error ( modulenum -- u )

Returns the contents of the 16-bit error flag located in the ether_info structure for the specified EtherSmart module. This flag is set by a number of the functions in this glossary at the same time the ether_response mailbox is written to, and in some cases the error code is also written as the least significant 16-bits in ether_response. Ether_Error is cleared by Ether_Error_Clear. The numeric (unnamed) error codes are as follows:

Value Meaning

0x08 ERROR_INVALID_RESPONSE // expected prompt or string not received

0x10 ERROR_NO_RESPONSE // no response from remote

0x20 ERROR_ALREADY_CONNECTED // only 1 connection is allowed at a time

0x40 ERROR_CANT_DISCONNECT // can't disconnect (for some reason)

0x80 ERROR_BUFFER_TOO_SMALL // buffer is too small

0x100 ERROR_TIMEOUT // timed out before operation could complete

0x200 ERROR_INVALID_PARAM // out of range or invalid parameter

C: void Ether_Error_Clear ( int modulenum )

4th: Ether_Error_Clear ( modulenum -- )

Writes 0 to the 16-bit Ether_Error error flag located in the ether_info structure for the specified EtherSmart module. Caution: The Ether_Error flag is typically written to by the Ethernet task, so executing Ether_Error_Clear from a routine running in the application task area will be asynchronous with respect to the setting of the flag. See Ether_Error for a list of error codes.

C: void Ether_Flush ( int modulenum )

4th: Ether_Flush ( modulenum -- )

C: void Ether_Flush_NBytes ( uint maxbytes, uint timeout_msec, int modulenum )

4th: Ether_Flush_NBytes ( maxbytes\timeout_msec\modulenum -- )

C: void Ether_Gateway ( char ip1, char ip2, char ip3, char ip4, int subnet_bits, int modulenum )

4th: Ether_Gateway ( ip1\ ip2\ ip3\ ip4\subnet_bits\modulenum -- )

Sets the 32-bit gateway IP (Internet Protocol) address pointed to by Ether_Gateway_IP_Ptr in the ether_info struct to the specified 4-byte value ip1.ip2.ip3.ip4 for the specified EtherSmart modulenum. Also sets the number of subnet bits for the Local Area Network (LAN) to the specified value. The gateway is the router computer on the LAN. The number of subnet bits is equal to the number of bits specified as zeros in the LAN’s netmask. For example, to set the gateway IP address to 10.0.1.2 with 8 subnet bits, pass to this routine the IP parameters 10, 0, 1, and 2 followed by 8, followed by the EtherSmart Wildcard modulenum. Setting the number of subnet bits to 8 is equivalent to specifying a “netmask” of 255.255.255.0, meaning that a maximum of 255 IP addresses can be represented on the LAN; this is a “type C” LAN. Specifying 16 subnet bits is equivalent to a netmask of 255.255.0.0, corresponding to a “type B” LAN. Specifying 24 subnet bits is equivalent to a netmask of 255.0.0.0, corresponding to a “type A” LAN. Assuming that you have initialized the Ethernet task (see Ether_Task_Setup), you can implement the specified information so that it is stored in XPort flash memory and used by the XPort by executing this function and Ether_Local_IP (see its glossary entry). Then, to instantiate the values in XPort flash, execute Ether_Update followed by Ether_Await_Response. To use a local IP, gateway IP and netmask that are automatically assigned, specify these as 0.0.0.0 (the factory default); then the XPort hardware relies on DHCP (Dynamic Host Configuration Protocol) running on the local area network’s DHCP server to set the IP address. To revert to the factory defaults which rely on a DHCP-assigned IP, gateway IP and netmask, execute Ether_XPort_Defaults. For a printed report of the local IP, gateway IP, and netmask, see Ether_IP_Info_Report.

C: xaddr Ether_Gateway_IP_Ptr ( int modulenum )

4th: Ether_ Gateway _IP_Ptr ( modulenum -- xaddr )

Returns the xaddress within the ether_info struct for the specified EtherSmart module that holds the packed 32-bit IP (Internet Protocol) address of the gateway server (router) on the LAN (Local Area Network). The 4 bytes of the gateway IP address are stored in order at the returned xaddress. Assuming that you have initialized the Ethernet task using Ether_Task_Setup, you can view the gateway IP address that is currently in use by the XPort hardware on the EtherSmart Wildcard by executing Ether_IP_Info_Request followed by Ether_Await_Response, and then fetching the 4 bytes from the xaddress returned by this routine. For example, if the gateway IP address is 10.0.1.2, the 10 will be stored at the returned xaddress, followed by the 0, the 1, and the 2 in sequential memory bytes. To use a gateway IP address that is automatically assigned by the LAN’s gateway host, specify an IP address and gateway IP and netmask of 0.0.0.0 (the factory defaults); then the XPort hardware relies on DHCP (Dynamic Host Configuration Protocol) running on the local area network’s gateway server to set the IP address. To revert to the factory defaults which rely on a DHCP-assigned IP, gateway IP and netmask, execute Ether_XPort_Defaults. For a printed report of the local IP, gateway IP, and netmask, see Ether_IP_Info_Report. See Ether_Local_IP and Ether_Gateway for more information about how to set the XPort’s IP address, gateway IP, and netmask.

C: void Ether_Get_Chars ( xaddr xlbuffer, uint maxbytes, uint maxlines, char eol,

int discard_alt_eol, int discard_msbit_set, uint timeout_msec, int modulenum )

4th: Ether_Get_Chars ( xlbuf\maxchars\maxlines\eol\discard.alt.eol\no.msbitset\timeout\module--)

Stores the specified input parameters into the ether_info struct and SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). Requests and stores incoming ASCII data from the specified EtherSmart modulenum. The data is stored into xlbuffer starting at the address xlbuffer+2, and the number of bytes received is stored as a 2-byte count at xlbuffer. The xlbuffer parameter is a 32-bit extended address that holds the 16-bit buffer count followed by the buffer data. The data input operation stops if the amount of data in the specified buffer (not including the 2-byte count) exceeds the specified maxbytes parameter. A maximum of maxlines are accepted, where a “line” is a data sequence ending in the specified eol (end of line) character. If the maxlines input parameter = -1, then the line limit is ignored. If maxlines = 0, then all except the last incoming line are discarded, and only the last line is stored into the buffer, excluding the final eol character which is discarded and not added to the buffer. The eol parameter is a single character that specifies End Of Line. Typical values are ‘CR’ = 0x0D or ‘LF’ = 0x0A. Dual-character sequences such as CRLF are not allowed. If eol_char = ‘LF’, we define the “alternate eol” is a ‘CR’. For all other eol chars (including a ‘CR’), the “alternate eol” is a ‘LF’. If the discard_alt_eol flag parameter is true, the alternate to the specified eol character is discarded/ignored by this routine. If the flag is false, the alternate eol char does not get special treatment, and is stored in the buffer like any other character. If the no_msbitset flag is true, then any characters having its most significant (ms) bit set (bit7, bitmask = 0x80) is discarded and is not stored in the buffer. This is useful, for example, if the incoming data is sent by a telnet application; some tty configuration data is transmitted that can be filtered out by discarding characters with their msbits set. This function exits within the specified timeout_msec whether or not the maximum number of bytes or lines have been accepted. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and numbytes_appended in the remaining 2 bytes is placed in the ether_response mailbox. To test for a buffer overrun, fetch the 2-byte count from xlbuffer and test whether it is greater than or equal to the allowed maxbytes. The specified maxbytes must be less than or equal to 65533 so that the maximum buffersize including count fits in a 16-bit number. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response. This routine must not be used to input binary (non-ascii) data; see also Ether_Get_Data and Ether_Add_Data.

Implementation detail: Writes a starting 16-bit count = 0 to the specified xlbuffer and calls Ether_Add_Chars.

C: void Ether_Get_Data ( xaddr xlbuffer, uint maxbytes, uint timeout_msec, int modulenum )

4th: Ether_Get_Data ( xlbuffer\maxbytes\timeout_msec\modulenum -- )

Implementation detail: Writes a starting 16-bit count = 0 to the specified xlbuffer and calls Ether_Add_Data.

C: void Ether_Get_Line ( xaddr xlbuffer, uint maxbytes, char eol, int discard_alt_eol,

int discard_msbit_set, uint timeout_msec, int modulenum )

4th: Ether_Get_Line ( xlbuffer\maxchars\eol\discard.alt.eol?\no.msbitset?\timeout_msec\module--)

Calls Ether_Get_Chars, passing 1 as the maxlines parameter to input a maximum of one line of text with the specified eol (end of line) character. See Ether_Get_Chars.

C: xaddr ether_gui_message

4th: ether_ gui_message ( -- xaddr )

A mailbox in common RAM that conveys a 32-bit function pointer (xcfa) from the Ethernet control task to the user’s application task. The programmer does not directly examine the contents of this mailbox; rather, the programmer’s application code monitors the contents of this mailbox using the non-blocking function Ether_Check_GUI function (see its glossary entry for details). When the Ether_Connection_Manager running in the Ether_Service_Loop detects a web request that involves a handler that was posted using HTTP_Add_GUI_Handler, it writes into this mailbox the 32-bit extended code field address of the handler associated with the incoming web address URL. The User Guide contains information about how to craft handler functions to implement a web-based “remote front panel” for an instrument.

C: xaddr Ether_Inbuf ( int modulenum )

4th: Ether_Inbuf ( modulenum -- xaddr )

Returns the 32-bit extended base address of the default buffer for incoming bytes from the Ethernet for the given module. This buffer is available for use by the programmer, and is typically (but not necessarily) passed as the target input buffer to functions such as Ether_Add_Data, Ether_Get_Data, Ether_Add_Chars, Ether_Get_Chars, Ether_Get_Line, and Ether_Add_Line. It can also be used as the “scratchpad buffer” for Ether_Send_Email. Note that these input routines treat this as an “lbuffer” with a 16-bit count stored in the first 2 bytes and the data following. Ether_Inbuf is modified by the following functions that use the XPort’s monitor mode: Ether_XPort_Defaults, Ether_XPort_Update, Ether_Ping_Request, Ether_Ping_Report, Ether_IP_Info_Request, Ether_IP_Info_Response, and Ether_Encryption. See the glossary entries for Ether_Inbufsize and Ether_Set_Inbuf. Ether_Inbuf should not be used for HTTP (web) service handlers which are dispatched from the Ethernet task; see HTTP_Inbuf.

C: uint Ether_Inbufsize ( int modulenum )

4th: Ether_Inbufsize ( modulenum -- u )

Returns the size of the Ether_Inbuf default input buffer for the specified EtherSmart module which is set by Ether_Info_Init and its callers, and/or by the Ether_Set_Inbuf function. Note that the allocated buffer size must be 2 bytes bigger than the maxnumbytes parameter passed to Ether_Init or Ether_Set_Inbuf; these 2 bytes provide room to store the 16- bit count at the start of the lbuffer. The Ether_Setup function initializes Ether_Inbufsize to ETHER_BUFSIZE_DEFAULT = 510, with an allocated buffer size of 512 bytes. This is above the recommended minimum ETHER_MIN_BUFFER_SIZE = 320.

C: xaddr Ether_Info ( int modulenum )

4th: Ether_Info ( modulenum -- xstruct_base )

Given the module number, fetches the 32-bit extended base address of the ether_info structure as stored by Ether_Info_Init and its callers (Ether_Init, Ether_Setup, Ether_Setup_Default, and Ether_Task_Setup). There is one ether_info struct per EtherSmart Wildcard. The ether_info struct contains the pointers and variables needed to specify the behavior of the corresponding EtherSmart Wildcard.

C: void Ether_Info_Init ( xaddr xinfo_struct_base, xaddr xautoserve_array_base, int numrows,

xaddr xbuffer_area_base, xaddr xcommand_mailbox, xaddr xresponse_mailbox,

xaddr xgui_mailbox, uint ether_inbufsize, uint ether_outbufsize,

uint http_inbufsize, uint http_outbufsize, int modulenum )

4th: Ether_Info_Init ( xinfo_struct_base\ xautoserve_array_base\numrows

\xbuffer_area_base\xcommand_mailbox\xresponse_mailbox

\xgui_mailbox\ether_inbufsize\ether_outbufsize

\http_inbufsize\http_outbufsize\modulenum --error)

Initializes the entries in the ether_info struct located at the specified xinfo_struct_base, and makes a table entry for the specified EtherSmart modulenum/ether_info pair so that the other driver functions can locate the xinfo_struct_base given the modulenum, and passes xautoserve_array_base and numrows to HTTP_Is_Autoserve_Array to allocate the autoserve array, then erases the autoserve array in RAM. Starting at the specified 32-bit xbuffer_area_base location which can be in paged or common RAM, allocates in order Ether_Inbuf having size specified by the ether_inbufsize parameter+2, Ether_Outbuf having size specified by the ether_outbufsize parameter+2, HTTP_Inbuf having size specified by the http_inbufsize parameter+2, and HTTP_Outbuf having size specified by the http_outbufsize parameter+2. The total number of bytes allocated for these buffers is:

8 + ether_inbufsize + ether_outbufsize + http_inbufsize + http_outbufsize

where the 8 + is for the 2-byte count at the beginning of each buffer. In other words, to allow for the 2-byte count to be stored before the content area of each buffer, the allocated size of each buffer is 2 bytes greater than the buffer contents size parameter that is passed to this routine. Stores a 16-bit zero into the first 2 bytes of each of these buffers to initialize each buffer count to zero. This function stores 0\0 into each of the 3 mailboxes ether_command, ether_response, and ether_gui_message specified by xcommand_mailbox, xresponse_mailbox, and xgui_mailbox, respectively. Each mailbox is specified by a 32-bit extended address that points to a 32-bit location in common RAM (mailboxes cannot be located in paged RAM). This function returns a zero flag if there is no error. If Ether_Info_Init detects that the specified size of the Ether_Outbuf or Ether_Inbuf is smaller than ETHER_MIN_BUFFER_SIZE = 320, it returns ERROR_BUFFER_TOO_SMALL = 0x80 and sets Ether_Error to this value (see Ether_Error). This is not a fatal error, but it is best to declare buffers that meet or exceed this minimum size so that all of the functions that rely on these buffers will work properly, including Ether_XPort_Defaults, Ether_Update, Ether_Ping_Request, Ether_Ping_Report, Ether_IP_Info_Request and Ether_IP_Info_Report. Note that the buffer sizes are available using the functions Ether_Inbuf, Ether_Outbuf, HTTP_Inbuf, and HTTP_Outbuf, and their sizes are available as Ether_Inbufsize, Ether_Outbufsize, HTTP_Inbufsize and HTTP_Outbufsize. This routine turns on the variables pointed to by HTTP_Enable_Ptr and Ether_Tunnel_Enable_Ptr. To disable one or both of these passive services, the program must turn them off explicitly by storing a zero after this routine (or its caller) executes. Initializes the contents of HTTP_Get_Timeout_Msec_Ptr to 5000 (a 5 second timeout for incoming HTTP requests), and initializes HTTP_Timeout_Msec_Ptr to 33000 (a 33 second timeout for outgoing web send operations). Installs the execution xaddress of HTTP_Default_Handler into the HTTP_Default_Handler_Ptr to serve out the “404 Not Found” error page. Sets Ether_Local_Port to its default value of 80 which allows auto-detection of incoming web and passive serial tunneling connections. Sets Ether_Internal_Webserver_Port to its default value of 8000; this is used to access the built-in web configuration tool. Ether_Info_Init is typically called by Ether_Init; see its glossary entry.

C: void Ether_Init ( xaddr xinfo_struct_base, xaddr xautoserve_array_base, int numrows,

xaddr xbuffer_area_base, xaddr xcommand_mailbox, xaddr xresponse_mailbox,

xaddr xgui_mailbox, uint ether_inbufsize, uint ether_outbufsize,

uint http_inbufsize, uint http_outbufsize, int modulenum )

4th: Ether_Init ( xinfo_struct_base\ xautoserve_array_base\numrows

\xbuffer_area_base\xcommand_mailbox\xresponse_mailbox

\xgui_mailbox\ether_inbufsize\ether_outbufsize

\http_inbufsize\http_outbufsize\modulenum -- error)

This is the fundamental initialization routine that must be invoked before accessing the UART or XPort hardware on the EtherSmart Wildcard. This routine calls Ether_Info_Init; see its glossary entry for a detailed description of its actions including initializing the ether_info struct, mailboxes, timeouts, and local port, and allocating the buffers. Ether_Init initializes the UART chip, powers up the XPort chip, starts the timeslicer and globally enables interrupts. This routine initializes the ether_service_module variable which specifies which module is controlled by the Ether_Service_Loop webserver and command processor running in the Ethernet task. (This routine does not initialize the ether_revector_module variable). This routine flushes the UART input buffers for 0.25 second if no connection is open. If there is an open Ethernet connection, this routine disconnects it, which takes 2.5 seconds. Ether_Init is typically called by Ether_Setup; see its glossary entry.

C: void Ether_Internal_Webserver_Port ( int portnum, int modulenum )

4th: Ether_Internal_Webserver_Port ( portnum\modulenum -- )

Writes the specified 16-bit internal (configuration) webserver portnum into the ether_info struct for the specified modulenum. This function is typically not used, as the default is typically retained. The default internal webserver port after executing Ether_XPort_Defaults is decimal 8000. To restore the default portnum, pass -1 or decimal 8000 to this function. Assuming that you have initialized the Ethernet task (see Ether_Task_Setup), you can instantiate the values in XPort flash after invoking this function by executing Ether_Update followed by Ether_Await_Response. To use the web configuration tool, type in the address bar of your browser the IP address of the XPort followed by : followed by the specified port number. For example, if the IP address is 10.0.1.22 and the internal webserver port is the default value of 8000, type in the browser address bar:

10.0.1.22:8000

The web configuration tool is self-explanatory, but be aware that changing certain parameters such as the serial configuration (baud rate, etc.) will render this driver code inoperable, and changing the internal webserver port from the web configuration tool itself may cause problems. To recover from such a mishap, initialize the Wildcard using Ether_Task_Setup, and then execute Ether_XPort_Defaults followed by Ether_Await_Response. Do not pass the value decimal 9999 to this function, as this is the reserved port for telnet setup and monitor modes. If you specify port 80 as the internal webserver port, be sure to change Ether_Local_Port to a different value.

C: void Ether_IP_Info_Report ( int modulenum )

4th: Ether_IP_Info_Report ( modulenum -- )

This is an interactive version of Ether_Info_Request, typically typed at a terminal, with the response printed to the terminal. This function retains control for up to approximately 7 seconds (that is, it’s a blocking function). This routine invokes the non-blocking function Ether_Info_Request which SENDs a command to the task running the Ether_Service_Loop, which in turn dispatches the action function. (If the mailbox is full, the SEND routine will PAUSE; see Ether_Ready_For_Command). This routine then RECEIVEs the results from the mailbox and prints the info result (along with any appropriate error message) to the terminal. An error code is returned via the ether_response mailbox; a nonzero return value results in a “ Couldn’t enter monitor mode!” printout. This routine awaits the response for you, so you do not need to clear the ether_response mailbox. The counted response string is at Ether_Outbuf, with the count in the first 2 bytes and the ascii response string (not including any error messages) following. If the info request was successful, the report is of the form:

IP 010.000.001.022 GW 010.000.001.002 Mask 255.255.255.000

which summarizes the IP address, gateway address, and netmask, respectively.

Note: The Lantronix firmware may report indeterminate results if DHCP (Dynamic Host Configuration Protocol) is enabled but there is no active network connection. DHCP is enabled by default and after Ether_XPort_Defaults is executed. To disable DHCP, assign a non-zero value to the local IP address, gateway IP, or netmask. See Ether_XPort_Update.

C: void Ether_IP_Info_Request ( int modulenum )

4th: Ether_IP_Info_Request ( modulenum -- )

SENDs a message via the ether_command mailbox to the task running the Ether_Service_Loop which dispatches the action function. (If the command mailbox is full because the action task hasn’t cleared it yet, the SEND routine will PAUSE; see Ether_Ready_For_Command). This function enters monitor mode and retrieves the local IP address, gateway IP address, and netmask that are currently in use by the XPort on the specified EtherSmart Wildcard. When the action function dispatched by the Ethernet task has completed, a response comprising the command byte in the most significant byte, module number in the next byte, and error flag in the remaining 2 bytes is placed in the ether_response mailbox; the error flag is also available using Ether_Error. The error flag is zero if the operation was successful, or nonzero if we couldn’t enter monitor mode. After calling this routine the application must clear the ether_response mailbox using Ether_Check_Response or Ether_Await_Response, but note that the result will not be present until over 7 seconds have elapsed, so please be patient. This routine can be used to discover which IP address, gateway and netmask were automatically assigned by the DHCP (Dynamic Host Configuration Protocol) server on the Local Area Network (LAN). After the ether_response mailbox has been read, the returned results are available by fetching 4 bytes each from the Ether_My_IP_Ptr, Ether_Gateway_IP_Ptr, and Ether_Netmask_Ptr locations (see their glossary entries). The counted ascii response string from the XPort is stored as a 2-byte count followed by the ascii data at Ether_Outbuf. For a printing version, see Ether_Info_Report.

C: uchar Ether_Key ( int modulenum )

4th: Ether_Key ( modulenum -- char )

For the specified EtherSmart module, waits for and returns the next pending input character. See Ether_Ascii_Key, Ether_Emit, Ether_Ask_Key, and E_Key.

C: void Ether_Local_IP ( char ip1, char ip2, char ip3, char ip4, int modulenum )

4th: Ether_Local_IP ( ip1\ip2\ip3\ip4\modulenum -- )

Sets the 32-bit IP (Internet Protocol) address pointed to by Ether_My_IP_Ptr in the ether_info struct to the specified 4-byte value ip1.ip2.ip3.ip4 for the specified EtherSmart modulenum. For example, to set the IP address to 10.0.1.22, pass the parameters 10, 0, 1, and 22 followed by the hardware modulenum to this routine. Assuming that you have initialized the Ethernet task (see Ether_Task_Setup), you can implement the specified IP address so that it is stored in XPort flash memory and used by the XPort by executing Ether_Local_IP. You should also invoke the Ether_Gateway function to specify the gateway IP address and netmask. Then, to instantiate the values in XPort flash, execute Ether_Update followed by Ether_Await_Response. To use an IP address that is automatically assigned by the LAN’s gateway host, specify an IP address of 0.0.0.0 (the factory default); then the XPort hardware relies on DHCP (Dynamic Host Configuration Protocol) running on the local area network’s gateway server to set the IP address. To revert to the factory defaults which rely on a DHCP-assigned IP, gateway IP and netmask, execute Ether_XPort_Defaults. For a printed report of the local IP, gateway IP, and netmask, see Ether_IP_Info_Report. See Ether_Gateway for more information about how to set the gateway IP address and netmask.

C: void Ether_Local_Port ( int portnum, int modulenum )

4th: Ether_Local_Port ( portnum\modulenum -- )

Writes the specified 16-bit local port number into the ether_info struct for the specified modulenum. The default local port after executing Ether_XPort_Defaults is decimal 80. To confirm or restore the default portnum, pass -1 or decimal 80 to this function. Assuming that you have initialized the Ethernet task (see Ether_Task_Setup), you can instantiate the values in XPort flash after invoking this function by executing Ether_Update followed by Ether_Await_Response. The local port number is the only port on which the XPort can receive incoming connections (excluding configuration connections such as setup and monitor mode, and the built-in configuration webserver). Changing the local port value from the default port 80 is not recommended, as it will make using the dynamic webserver more difficult: the end user will have to type in the browser’s address bar the :portnum notation after the URL to specify the XPort’s destination port. Do not pass the value decimal 9999 to this function, as this is the reserved port for telnet setup and monitor modes. Do not pass the value decimal 8000 to this function, as this is the default value for the built-in web configurator tool. If portunm = 0 is specified, then the source port on outgoing (active) connections is a random number between 50000 and 59999.

C: ETHER_MIN_BUFFER_SIZE

4th: ETHER_MIN_BUFFER_SIZE

A 16-bit constant that returns the value 320. This constant is used by Ether_Init to test whether the specified the sizes of the Ether_Outbuf and Ether_Inbuf buffers are big enough to handle the default uses of the buffers for XPort configuration via the Ether_XPort_Defaults and Ether_Update functions. The ETHER_BUFSIZE_DEFAULT constant that is used by Ether_Setup equals 510 bytes, easily passing the constraint. If Ether_Info_Init and/or Ether_Init detects that the specified size of the Ether_Outbuf or Ether_Inbuf is smaller than 320, it sets Ether_Error to ERROR_BUFFER_TOO_SMALL = 0x80 (see Ether_Error). This is not a fatal error, but it is best to declare buffers that meet or exceed this minimum size.

C: void Ether_Monitor ( void )

4th: Ether_Monitor ( -- )

An infinite task loop that calls Ether_Serial_Revector and then invokes the QED-Forth monitor routine named QUIT. Executing this routine, or using it as the activation function for a task causes serial I/O for the affected task to be revectored to the EtherSmart Wildcard whose modulenum is stored in the ether_revector_module global variable. Make sure that you initialize ether_revector_module before executing this function or using this function as a task activation routine via the ACTIVATE kernel function.

Usage notes: See the demo program for an example of use. Store the correct modulenum that corresponds to the hardware jumper settings of the EtherSmart Wildcard into the global variable named ether_revector_module, then call Ether_Monitor. This will run the default (startup) task through the specified EtherSmart wildcard. To communicate with the terminal, use the "Rlogin" mode of the Putty Ethernet terminal program to connect to the local port (typically = 80) at the specified EtherSmart IP address (see Ether_Local_IP), and you're talking to the QED monitor via Ethernet. To revert to standard serial operation via QED Term, type COLD in the Ethernet terminal window to revert to standard serial, then from QEDTerm type RESTORE to bring back access to all compiled routines, then continue communications using QEDTerm. If you want to maintain serial communications via QEDTerm with the default task while running a separate task with I/O revectored via the EtherSmart Wildcard, then build and activate a task using Ether_Monitor as the activation routine as shown in the demo code. Use Putty "Rlogin" to connect to the local port (typically port 80) at the specified EtherSmart IP address, and you're talking to the task via Ethernet.

To obtain the free Putty Ethernet terminal program, type

Putty

into your search engine (such as Google) and download the free telnet program from one of the listed sites. It is a small and simple yet generally useful program.

C: xaddr Ether_My_IP_Ptr ( int modulenum )

4th: Ether_My_IP_Ptr ( modulenum -- xaddr )

Returns the xaddress within the ether_info struct for the specified EtherSmart module that holds the packed 32-bit IP (Internet Protocol) address of the XPort. The IP address is used by the network to uniquely identify the EtherSmart Wildcard, and consequently the IP address must be unique on the Local Area Network (LAN) containing the EtherSmart Wildcard. The 4 bytes of the IP address are stored in order at the returned xaddress. Assuming that you have initialized the Ethernet task using Ether_Task_Setup, you can view the IP address that is currently in use by the XPort hardware on the EtherSmart Wildcard by executing Ether_IP_Info_Request followed by Ether_Await_Response, and then fetching the 4 bytes from the xaddress returned by this routine. For example, if the IP address is 10.0.1.22, the 10 will be stored at the returned xaddress, followed by the 0, the 1, and the 22 in sequential memory bytes. To use an IP address that is automatically assigned by the LAN’s gateway host, specify an IP address of 0.0.0.0 (the factory default); then the XPort hardware relies on DHCP (Dynamic Host Configuration Protocol) running on the local area network’s gateway server to set the IP address. To revert to the factory defaults which rely on a DHCP-assigned IP, gateway IP and netmask, execute Ether_XPort_Defaults. For a printed report of the local IP, gateway IP, and netmask, see Ether_IP_Info_Report. See Ether_Local_IP and Ether_Gateway for more information about how to set the XPort’s IP address, gateway IP, and netmask.

<< Previous | Next>>

The EtherSmart Wildcard Glossary

Table of Contents

Glossary of EtherSmart Wildcard Driver Functions