Mux Reference¶

For details on using Mux as a line protocol, please see TruPort Socket (Mux).

Initial Setup¶

The selected serial Line on the device must be configured with Protocol set to “Mux” and with line settings compatible with the connected device. Some kind of flow control is required.

The Mux intentionally has no configurables, as its behavior is governed entirely by the Mux commands themselves.

Note

When Bridging is enabled on Interface ap0 or wlan0, Mux network connections to that Interface will not work, since inbound packets are sent to the bridged device.

Some commands offer binary-escape encoding for data transfer. To use these commands, data must be 8 bits (not 7) and flow control must be hardware (not software). If these commands cannot be used due to the line settings, data transfer can be achieved via alternate commands using hex encoding.

Commands¶

Mux provides machine to machine data communication, so it differs from the command line in the following ways:

Command characters are NOT echoed.
Each command is terminated by a single <CR> or <LF> character unless designated otherwise.
Commands are terse.
Responses are terse.
No tab completion.
No help text.
Times out when command character(s) received but not yet ended with newline.

Most commands comprise readable ASCII characters. The exceptions use binary-escape encoding, but these have a hex encoding alternate.

In the following commands, <n> is a whole number such as 1, 2, or 3 that indicates the connection instance.

Controlling Connections¶

A “Virtual” Connection establishes the configured Line Protocol on a virtual port.

An “Accept” Connection listens on a designated port for a connection attempt from the network. More than one may be set up and used at a time. Once a connection is established, the device stops listening on the designated port; at this time the host may choose to begin accepting with the same port on another accept instance.

A “Connect” Connection initiates the attempt into the network. It must be provided with the destination port and address. More than one may be set up and used at a time.

`Q`¶

Query for an unused instance.

Possible responses:

Response	Description
`<n>K`	Connection instance <n> is currently unused.
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>v<port>`¶

Establish connection to a virtual port where <port> is ad decimal number 1 for Virtual_1, 2 for Virtual_2, and so on designating the virtual port.

Possible responses:

Response	Description
`K`	Successful
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>l<line name>`¶

Establish connection to a line whose Protocol is “None”, where <line name> is the name of such a Line, such as “1” or “CDC_ACM”.

Possible responses:

Response	Description
`K`	Successful
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>a[<interface>:]<port><protocol>[,<credential>]`¶

Begin listening for a connection from a remote node on the network.

Argument	Description
`<n>`	The instance number
`<interface>`	Can be ap0 or wlan0 to restrict listening to that specific interface; optional for TCP based protocols but required for UDP based protocols
`<port>`	A decimal number from 1 to 65535 representing the port to listen on
`<protocol>`	Can be “TCP”, “TCP AES”, "TLS", "UDP"
`<credential>`	The name of the credential to be used, present only if the protocol requires a credential.

Possible Responses:

Response	Description
`K`	Successfully waiting for an inbound connection; may become Active any time
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>c[<local port>]<destination>:< port>[.]<protocol>[,<credential>]`¶

Begin connecting.

Argument	Description
`<n>`	The instance number
`<local port>`	Optional; if present, it is a decimal number surrounded by square braces from 1 to 65535 representing the local port
`<destination>`	Either a hostname or an IP address
`<port>`	The optional “.” after `<port>` designates non-blocking connect (this requires more RAM; without the “.”, this command will not return until the connection completes or fails)
`<protocol>`	Can be “TCP”, “TCP AES”, "TLS", “UDP”
`<credential>`	The name of the credential to be used, present only if `<protocol>` requires a credential.

Possible responses:

Response	Description
`K`	Waiting for an outbound connection; will reach either Active or Disabled over time.
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>h`¶

Begin listening for HTTP.

This option works with the HTTP server, listening for a transaction directed to the URL “/mux_http”.

Possible responses:

Response	Description
`K`	Successfully waiting for an inbound connection; may become Active any time
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>p`¶

Pushes out pending send data.

Possible responses:

Response	Description
`K`	Successful
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>e[<timeout>]`¶

Ends the instance gracefully, pushing out pending send data over time but immediately dropping any receive data, where

optional <timeout> is a number representing milliseconds for timeout – if not provided, a 5000 msec timeout applies.

Possible responses:

Response	Description
`K`	Successful
`T`	Timed out before all the data could be sent; instance is not ended
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>f[<timeout>]`¶

Sends fin, pushing out pending send data over time but receive direction remains open, where

optional <timeout> is a number representing milliseconds for timeout – if not provided, a 5000 msec timeout applies.

Possible responses:

Response	Description
`K`	Successful
`T`	Timed out before all the data could be sent; instance remains open for send
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>k`¶

Kills the instance without delay.

Possible responses:

Response	Description
`K`	Successful
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>`¶

Requests current status of the instance.

Possible responses:

Response	Description
`D`	Disabled
`W`	Waiting for connection establishment
`F`	Received fin, but send remains active
`R`	Sent fin, but receive remains active
`K`	Active

Transferring Data¶

In the following commands, <bytes> is a decimal number in ASCII numeric characters.

`<n>x<encoded escape sequence>`¶

Switch to <n> for bidirectional transfer, where <encoded escape sequence> represents <escape sequence> which the host will send and look for. Alphanumeric characters do not need to be encoded.

The following encoding rules are supported:

\n                  newline,
\r                  carriage return,
\\                  backslash,
\0                  the null character,
\xhh                hexadecimal (hh),
\dmmmm              delay decimal (mmmm) milliseconds; this delay (if specified)
                    must be present after <escape sequence>,
\tmmmmm             send data time out (mmmmm) milliseconds will close the network
                    connection.

Possible responses are:

Response Description

K Successful. Now the host sends and receives bytes on <n>.
The host sends <escape sequence> to pause the transfer. The device may still be sending some data, and subsequently sends <escape sequence> to acknowledge termination. The host is now back to the Mux command level.
The device may terminate <instance> by sending <escape sequence>. In this situation the host must still send <escape sequence> to return to the Mux command level.

E<string><LF> Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>sx`¶

Send data coded in hex.

Possible responses:

Response	Description
`<bytes>K`	Okay for no more than <bytes> number of bytes. Now the host sends hex bytes. The host sends a newline character to terminate. The device may terminate while the host is still sending bytes by sending <E<LF>; otherwise the device will acknowledge the host terminating newline by sending <K>. The host may decide not to send all the bytes that are allowed.
`E<string><LF>`	Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>sb<escape>`¶

Send data coded in binary-escape.

Possible responses:

Response Description

<bytes>K Okay for no more than <bytes> number of bytes.
Now the host sends binary bytes.
To send a byte that matches <escape>, host sends it twice in a row.
The host sends <escape> followed by a newline to terminate. The device may terminate while the host is still sending bytes by sending <E<LF>; otherwise the device will acknowledge the host terminating newline by sending <K>.
The host may decide not to send all the bytes that are allowed.

E<string><LF> Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>rx<bytes>[.]`¶

Receive up to <bytes> number of bytes coded in hex.

Possible responses:

Response Description

<bytes>K Accepted. The host will possibly wait indefinitely until data arrives. As data arrives, device sends to the host in hex.
Device sends <LF> after data when it terminates data mode.

Data mode terminates when:
1. If “.” ends the command, last byte of an incoming packet was read.
2. Number of bytes specified in command has been reached.
3. Connection is dropped.
4. Any single character is sent by the host.

E<string><LF> Error, where <string> is a readable ASCII message terminated by a Line Feed.

`<n>rb<escape><bytes>[.]`¶

Receive up to <bytes> number of bytes coded in binary-escape.

Possible responses:

Response Description

<bytes>K Accepted. The host will possibly wait indefinitely until data arrives. As data arrives, device sends to the host in binary.
Device sends <LF> after data when it terminates data mode.

Data mode terminates when:
1. If “.” ends the command, last byte of an incoming packet was read.
2. Number of bytes specified in command has been reached.
3. Connection is dropped.
4. Any single character is sent by the host.

E<string><LF> Error, where <string> is a readable ASCII message terminated by a Line Feed.

Waiting for Events¶

In the following command,

<event> is <n>[s|r] where s is for send ready and r is for receive ready, and <event list> is one or more concatenated events.

`W<event list>`¶

Wait for any of the listed events.

Possible responses:

Response Description

<bytes>K Agreed to the event list. Then, if any event in the list occurs, the first is returned, for example 2r<LF>. The device will wait indefinitely for any event on the list.
Host may cancel waiting by sending any single character. Device will not discard the character, so the host may send a newline for no operation or simply begin the next desired command.
Device confirms cancellation by sending a single <LF>.

E<string><LF> Error, where <string> is a readable ASCII message terminated by a Line Feed.

Device Control¶

General device control is achieved via the Command Line Interface. Connections can remain open during this time.

`D`¶

Enters Command Line Interface, but with echo off. Exit from the top level returns to Mux commands.

Examples¶

Note

In the following examples, commands are bold and responses are normal weight.

Hello World¶

Sends hello world to whoever connects TCP to port 10001.

Mux Commands

Description

1a10001TCP
KW1s
K1s
1sb~
50KHello world!~

K1e
K

Listen TCP on port 10001; we use TeraTerm to connect in for this example
Wait for instance 1 ready for us to send data
K upon connection. 1s indicates that instance 1 can be sent data
Request to send binary on instance 1 to be terminated by ~ then newline
Cleared to send up to 50 bytes in this transaction. Hello World!~ provides data and terminates command
Cleanly push out data and sends FIN to close connection

Connecting Out and Reading¶

Connects to remote host and reads data.

Mux Commands

Description

1c172.19.100.11:23TCP
KW1r
K1r
1rb~2000
K
Command Line started.
>1
~
K

Supplies address CLI port of another xPico200 device, just for this example
Wait for instance 1 has data for us to read
K upon connection. 1r = instance 1 has data waiting for us to read
Initiates read binary up to 2000 bytes terminated by ~ then newline

Query instance 1 state serves to request early end of read
~ then newline from Mux signifies end of binary read command
Answer to instance 1 query—connection remains up

Connecting out and Bidirectional Transfer¶

Connects to remote host and transfers data bidirectionally until escaped.

Mux Commands

Description

1c172.19.100.11:23TCP
KW1r
K1r
1x+++\d0100
K
Command Line started.
>ssttaattuuss
status>+++
1

K

Supplies address CLI port of another xPico200 device, just for this example
Wait for instance 1 has data for us to read
K upon connection 1r = instance 1 has data waiting for us to read
Initiates bidirectional transfer terminated by +++ then delay

Delayed 100 msec +++ signifies end of bidirectional transfer
Query instance 1 state, necessary that we waited for +++ confirmation from Mux
Answer to instance 1 query—connection remains up

Mux Reference¶

Initial Setup¶

Commands¶

Controlling Connections¶

Q¶

<n>v<port>¶

<n>l<line name>¶

<n>a[<interface>:]<port><protocol>[,<credential>]¶

<n>c[<local port>]<destination>:< port>[.]<protocol>[,<credential>]¶

<n>h¶

<n>p¶

<n>e[<timeout>]¶

<n>f[<timeout>]¶

<n>k¶

<n>¶

Transferring Data¶

<n>x<encoded escape sequence>¶

<n>sx¶

<n>sb<escape>¶

<n>rx<bytes>[.]¶

<n>rb<escape><bytes>[.]¶

Waiting for Events¶

W<event list>¶

Device Control¶

D¶

Examples¶

Hello World¶

Connecting Out and Reading¶

Connecting out and Bidirectional Transfer¶

`Q`¶

`<n>v<port>`¶

`<n>l<line name>`¶

`<n>a[<interface>:]<port><protocol>[,<credential>]`¶

`<n>c[<local port>]<destination>:< port>[.]<protocol>[,<credential>]`¶

`<n>h`¶

`<n>p`¶

`<n>e[<timeout>]`¶

`<n>f[<timeout>]`¶

`<n>k`¶

`<n>`¶

`<n>x<encoded escape sequence>`¶

`<n>sx`¶

`<n>sb<escape>`¶

`<n>rx<bytes>[.]`¶

`<n>rb<escape><bytes>[.]`¶

`W<event list>`¶

`D`¶