ScanImage® Remote Control (TCP/IP)

ScanImage® includes a TCP/IP server and client that can be used to execute Matlab commands on a remote computer. Simply open the server on the ScanImage® computer and open the client on the the remote computer. Then, ScanImage® can be controlled through the command line.

Matlab Remote Server

To launch the server, specify the remote computer’s IP address and the server port. Call the constructor to get the server handle. Note that the port is hardcoded to 5555.

>> IPWhitelist = {'127.0.0.1/32'};       % Use your remote computer's IP address
>> serverPort = 5555;                    % serverPort is hardcoded to 5555
>> hServer = most.network.matlabRemote.Server(5555,IPWhitelist);

hServer =
   Server with properties:
      port: 5555
      IPWhitelist: {'127.0.0.1/32'}

To shutdown the server, call delete() on the server.

>> hServer.delete();

Warning

Launching the TCP/IP server allows full control over the computer, including the execution of code. The data between client and server is not encrypted, and no authentication is required. The IP white list allows to reject unknown clients, but only provides a minimal level of security. Only use the server on a private and trusted network.

---

Matlab Remote Client

To create the client, supply the ScanImage computer’s IP address and the server port.

>> serverAddress = '127.0.0.1';           % Use the ScanImage computer's IP address
>> serverPort = 5555;
>> hClient = most.network.matlabRemote.Client(serverAddress,serverPort);
   Connected to server running Matlab 9.6.0.1072779 (R2019a)

>> hClient.feval('disp','Hello World!');  % Execute a function on the server
>> myData = rand(3)                       % Create a local variable with some data

myData =
   0.1023 0.7350 0.4641
   0.9614 0.9924 0.6104
   0.1540 0.4698 0.9597

>> myData_server = hClient.upload(myData) % Upload data to the server

myData_server =
   ServerVariable on server 127.0.0.1:5555
   Class: double
   Size: [3 3]

>> myData_server = myData_server + 100;   % Manipulate the data on the server
>> myData = myData_server.download()      % Retrieve the data from the server

myData =
   100.1023 100.7350 100.4641
   100.9614 100.9924 100.6104
   100.1540 100.4698 100.9597

>> hClient.delete();

Note

All calls to the server are synchronous. This means the client Matlab console is blocked until the server finishes executing the command.

---

ScanImage® Control

The TCP/IP server exposes all ScanImage® functionality via ScanImage’s API calls. The following is an example of connecting to the host computer, starting ScanImage, and using the hSI object (note that the TCP/IP server needs to be started on the remote computer first):

serverAddress = '127.0.0.1';   % Use the ScanImage computer's IP address
serverPort = 5555;
>> hClient = most.network.matlabRemote.Client(serverAddress,serverPort);
   Connected to server running Matlab 9.6.0.1072779 (R2019a)

% Start ScanImage, provide MDF path to suppress startup modal, and store hSI reference
>> hSI_server = hClient.feval('scanimage','C:\Machine_Data_File.m');
>> hSI_server.startFocus();
>> lastFrame_server = hSI_server.hDisplay.lastFrame
lastFrame_server =
   ServerVariable on server 127.0.0.1:5555
   Class: cell
   Size: [1 1]

>> lastFrame = lastFrame_server.download()
   ans =
      1×1 cell array
      {512×512 double}

>> hSI_server.abort();
>> hSI_server.exit();
>> hClient.delete();

To retrieve the hSI handle from an already running ScanImage® instance, execute the following command:

(The TCP/IP server needs to be started on the remote computer first)

serverAddress = '127.0.0.1';
serverPort = 5555;
>> hClient = most.network.matlabRemote.Client(serverAddress,serverPort);
   Connected to server running Matlab 9.6.0.1072779 (R2019a)

>> hSI_server = hClient.feval('evalin','base','hSI'); % retrieve hSI handle from server base workspace