The MX Foundation 4 API (MXF4) is designed around the Client-Server model.

Ethernet connection allows an MXF4 client application to access MAX Technologies resources on a LAN such as FlexMAX, FlexMulti or FlexMobile device. Also any distant computer on a LAN with installed MAX Technologies PCI/PXI-Express cards and running MXF4 server software can be controlled remotely by a MXF4 client application.

An MXF4 client application begins by calling one of the mxfConnect functions to select between Ethernet, USB or PCI/PXI-Express devices.

The same application, only by changing the mxfConnect functions, can communicate with various MAX Technologies devices supporting Ethernet, USB or PCI/PXI-Express connection.

MXF4 server access

MXF4 server user control

All these functions are detailed in the Connection section.

Connection

There are three types of connection:

Of the three connection modes, Ethernet is the most flexible, especially with FlexMulti devices or FlexMAX chassis. Gigabit Ethernet is fast, allows devices access from any Windows, Linux, macOS or iPadOS client apps and doesn't require to install and maintain of device drivers on the computer. Also Ethernet connection allows configuring access control list (ACL) to Flex devices if desired enabling device access from only permitted clients.

Ethernet Connection

Ethernet connection allows an MXF4 client application to access MAX Technologies resources on a LAN. Such resource can be any MAX Technologies device supporting Ethernet connection such as FlexMAX, FlexMulti or FlexMobile products. Also any computer running MXF4 Server software with installed MAX Technologies PCI/PXI-Express cards can be controlled remotely using the Ethernet connection.

The exact same function calls are used by the client to communicate with MX Foundation API. All the methods to translate the function call into the command to be executed by the server is hidden inside MX Foundation. Only the parameters to the mxfConnectEthernet() function are changed to establish the connection to the remote server.

In order to establish the connection:

the URL must point to a valid network address (IPv4 dotted-decimal format) or the device hostname.
the username must be specified as defined below.
the password must be specified as defined below.
the exclusive control can optionally be used to have exclusive access to the server resources.

The device hostname is unique and always refers to the same device on a LAN so it is recommended to connect remotely. Using the device hostname instead of its IP address insure your application will always find the corresponding device when online and connect to it even if its IP address has changed. Use the FindDevices tool to discover the MAX Technologies devices on a LAN and display the corresponding hostnames.

When the client accesses a server on another system, a network connection must be established between the network endpoints. This means both endpoints are subject to network access rules that are configurable on the client and the server; routing, firewall, etc.

The examples below illustrates a typical remote connection using either device IP address or device hostname.

int main()
{
HMXF_SERVER  server;
HMXF_DEVICE  device;
uint32 rc;
    // Connect to MAX Technologies device on a LAN at address 10.0.1.102 
    rc = mxfConnectEthernet("10.0.1.102", "admin", "admin", FALSE, &server);   
    // MXF4 Library initialization
    if (!rc)
       rc = mxfSystemInit(server);
    // Get the device handle
    if (!rc)
       rc = mxfSystemDeviceGet(server, 0, &device);
    ...
    if (rc)
        printf("Error code=0x%lX\n", rc);
    mxfSystemTerminate(server);
    mxfServerDisconnect(server);
}

int main()
{
HMXF_SERVER  server;
HMXF_DEVICE  device;
uint32 rc;
    // Connect to a MAX Technologies FlexMulti 1553 device on a LAN using its device hostname 
    rc = mxfConnectEthernet("FlexMulti_1553-3A7B6783.local", "admin", "admin", FALSE, &server);   
    // MXF4 Library initialization
    if (!rc)
       rc = mxfSystemInit(server);
    // Get the device handle
    if (!rc)
       rc = mxfSystemDeviceGet(server, 0, &device);
    ...
    if (rc)
        printf("Error code=0x%lX\n", rc);
    mxfSystemTerminate(server);
    mxfServerDisconnect(server);
}

USB Connection

USB connection allows an MXF4 client application to access the Flex devices connected by USB to the same computer. Only one application can connect to a USB device at a time. An application can connect to more than one USB device.

In USB mode, mxfSystemUSBDetect() and mxfConnectUSB() are used to detect the MAX Technologie USB devices and connect to it.

The example below illustrates a typical USB connection.

int main()
{
HMXF_SERVER  server;
HMXF_DEVICE  device;
uint32 rc;
uint64 usbDevCount;
    // Detect MAX Technologies USB device connected
    rc = mxfSystemUSBDetect(&usbDevCount);
    if(!rc && !usbDevCount)
    {
       printf("No MAX Technologies USB device detected\n");
       return MAXT_ERROR_DEVICE_NOT_DETECTED;
    }
    // Connect to the first USB device
    if(!rc)
      rc = mxfConnectUSB(0, &server);
    // MXF4 Library initialization
    if (!rc)
        rc = mxfSystemInit(server);
    // Get the device handle
    if (!rc)
      rc = mxfSystemDeviceGet(server, 0, &device);
    ...
    if (rc)
        printf("Error code=0x%lX\n", rc);
    mxfSystemTerminate(server);
    mxfServerDisconnect(server);
}

PCI/PXI-Express

PCI/PXI-Express connection allows an MXF4 client application to access the MAX Technologies devices installed in the same computer via PCIe, PXIe or Thunderbolt.

In PCI/PXI-Express connection, there is no authentication checking for the connection.

The example below illustrates a typical PCI/PXI-Express connection.

int main()
{
HMXF_SERVER  server;
HMXF_DEVICE  device;
uint32 rc;
    // Connect to the MAX Technologies PCI/PXI-Express resources
    rc = mxfConnectPCIE(&server);   
    // MXF4 Library initialization
    if (!rc)
       rc = mxfSystemInit(server);
    // Get the device handle
    if (!rc)
       rc = mxfSystemDeviceGet(server, 0, &device);
    ...
    if (rc)
        printf("Error code=0x%lX\n", rc);
    mxfSystemTerminate(server);
    mxfServerDisconnect(server);
}

With the exception of the initial connection, the client application is unchanged and uses exactly the same code as the local version.

Ethernet Access Control List (ACL) and privileges

Three connection privileges are available: user, advanced and admin.

The flexchangeacl command line tool is used to manage the ACL and privileges on a Flex device. The following describe the MXF4 APIs allowed for each level of privilege.

user

Normal user must open server connection in exclusive mode only. Cannot force the closing of other server connections.

Some functions are not available to normal user:

mxfSystemResourcesInit(). User must use mxfSystemInit().
mxfSystemResourcesRelease(). User must use mxfSystemTerminate().
mxfServerUserCountGet()
mxfServerUserListGet()
mxfServerUserDisconnect()

advanced

Advanced user can open server connection with either exclusive or non-exclusive mode, but cannot force the closing of other server connections.

Some functions are not available to advanced user:

admin

Admin user can open server connection with either exclusive or non-exclusive mode, and can force the closing of any server connection.

Admin is the highest privilege level. All functions are available to admin user including contoling access to other lowest level privileges.

Advanced Ethernet Configuration

Keepalive mechanism and default port can be changed.

Keepalive

Both client and server use a keepalive mechanism to detect lost of connection. When debugging the client application, stopping on a breakpoint will prevent the client from responding to the server and if it takes too much time to resume the client application, the server will consider that the connection to the client has been lost and will close the connection. The client application will receive a "socket connection aborted" error in that case and will need to reconnect to the server. This behavior can be changed with the KMXF_SERVER_KEEP_ALIVE attribute.

Default port

By default, port 30000 is used but can be changed with the configuration file. If the default port is not available, the connection will try to be established on the first available port of the 99 next port from the default port (by default port 30000 to 30099 can be used).

mxf_server.conf

The file mxf_server.conf defines the network connection port.

This file is located in the maxfiles folder:

Windows: ProgramData\MAX Technologies\mx_foundation\maxfiles
Embedded Linux: /maxfiles

[general]
port = 30000