This note details how to implement a Graphical User Interface (GUI) application in order to remotely control a B-Box PRO or B-Board system. The application is built on MATLAB App Designer (formerly MATLAB GUI) and the communication is achieved by using UDP/Ethernet packets.

Please note the Closing comments about the performance/responsiveness of this approach.

Software resources

To be completed...

MATLAB App Designer

Being part of MATLAB basic package, App Designer enables to conveniently design graphical user interfaces by dragging and dropping visual components. Actions and processes are meant to be implemented in the well-known MATLAB programming language. At a later stage, standalone applications can be built and launched on any computer using the free MATLAB Runtime.

MATLAB Help Center provides many tutorials on their App Designer product, e.g. Create and Run a Simple App Using App Designer. Other resources like this might be worth a look.

Ethernet communication

B-Box RCP and B-Board PRO support data communication protocols by providing high-level functions or blocks that allow the user to conveniently send and receive data. The present example has been implemented using UDP over Ethernet communication, because of its broad availability.

Since the UDP-related functions are part of MATLAB Instrument Control Toolbox, this example uses judp a freely available UDP communication library.

Data exchange planning

A few basic principles apply to the UDP communication with B-Box RCP and B-Board PRO:

  • Packets must be 4 bytes long

  • Consequently, they are usually carrying one variable of 32 bits each

  • In order to allow communication of multiple variables, the system implements communication mailboxes, each mailbox being listening or sending to a given UDP port

The timing of the packets is defined such that:

  • When the user code reads a packet, it gets the latest one (on the mailbox port), even though no packet was received between two reads.

  • When the user code writes a packet, it is sent immediately. The send rate is limited, though.

Based on the above-mentioned considerations, a list of data exchanges is built as follows.

Port

Destination

Description

Data type

Comments on data content

2222

Computer

Custom action result (counter)

uint32


2223

B-Box RCP

Custom action

uint32

1: A 2: B

2224

B-Box RCP

Start/Stop action

uint32

To stop, send 0, to start send 1

2225

Computer

Core state

uint32

2: enabled 1:disabled (struct tCoreState)

2226

B-Box RCP

DC bus reference

float32

Must be saturated in B-Box

2226

Computer

DC bus measurement

float32


2227

B-Box RCP

Id setpoint

float32


2227

Computer

Id measurement

float32


2228

B-Box RCP

Iq setpoint

float32


2228

Computer

Iq measurement

float32


2229

Computer

Vac measurement

float32


2230

Computer

Vbat measuremeent

float32


2231

B-Box RCP

Precharge relay action

uint32

1: close relay, 0: open relay

2231

Computer

Precharge relay state

uint32

1: closed 2: open

2232

B-Box RCP

AC relay action

uint32

1: close relay 0: open relay

2232

Computer

AC relay state

uint32

1: closed 2:open

C code implementation overview

The initialization of input and output mailboxes should be implemented inside function tUserSafe UserInit(void) {}. Typical initialization looks like:

constexpr unsigned int MB_ACTION_RESULT = 0;
constexpr unsigned int MB_ACTION 		= 1;

char ip_address[] = "10.10.10.53";
float update_frequency = 100.0;

tUserSafe UserInit(){

	// ...
	Eth_ConfigureOutputMailbox(MB_ACTION_RESULT, 2222, ip_address, update_frequency);
	Eth_ConfigureInputMailbox(MB_ACTION, 2223);
	// ...

}

At run-time, the following calls can be made so that to access the received data or send new packets:

start_cnt = Eth_ReadUint(MB_ACTION);
Eth_Write(MB_ACTION_RESULT, payload);

Even though the Eth_Write() function is called at each execution of the control loop, the underlying operating system makes sure that the message is not sent faster than the update_frequency passed in parameter at initialization.

ACG code implementation overview

‘Ethernet input mailbox’ and 'Ethernet output mailbox' blocks (available in the imperix library) should be inserted in the Simulink files to ensure the communication with the GUI.

The "Ethernet input mailbox" block receives the information from the GUI. The Ethernet port number and the signal format must be specified in the block settings.

The "Ethernet output mailbox" block sends the information to the GUI. The Ethernet port number, the Ethernet IP address (of the PC on which the GUI is running), the signal format and the sending frequency must be specified in the block settings.

Implementation principles in App Designer

Initialization

Besides the instantiation of the controls, the application implements a few properties:

  • app.timer object which will be used to trigger the data refresh

  • isconnected variable that stores the connection state

  • time variable that allows time counting

A startup function is implemented in order to configure the timer callback properly.

function startupFcn(app)
  app.timer.TimerFcn = @(~, ~) readEthernetandUpdate(app);
  % inits the timer (not stared yet,though. Done by ConnectButtonPushed())
end

Background processes

As long as isconnected > 0 a refresh task (readEthernetandUpdate()) is triggered by a timer with a period of 0.5 seconds. An excerpt of the function is:

function readEthernetandUpdate(app)
	app.time = app.time + 0.5;
	
	if   (typecast(flip(typecast(judp('RECEIVE',2225, 4), 'uint8')'),'uint32'))>1
		app.StateLamp.Enable = 1;
	else
		app.StateLamp.Enable = 0;
	end
	
    % ... (truncated)
    
	app.IdGauge.Value = ...
		double(typecast(flip(typecast(judp('RECEIVE',2227, 4), 'uint8')'),'single'));
	app.IqGauge.Value = ...
		double(typecast(flip(typecast(judp('RECEIVE',2228, 4), 'uint8')'),'single'));
	
    % ... (truncated)	
    
end

Actions

Actions (i.e. sending data from the computer) are implemented via callbacks on GUI elements. Two examples are presented below, one sending a uint32 and the second a float32. Typecasting as well as byte flipping must be implemented as follows.

function DisableButtonPushed(app, event)
  if app.isconnected % performs the action only when connected
    judp('SEND', 2224, app.BBoxIPEditField.Value, int8([0 0 0 1]'));
  end
end
function DCbusreferenceEditFieldValueChanged(app, event)
  value = app.DCbusreferenceEditField.Value;
  if app.isconnected
    judp('SEND', 2226, app.BBoxIPEditField.Value, flip(typecast(single(value), 'int8'))');
  end
end

Please make sure that you properly configure the Windows firewall in order to allow inbound UDP traffic.

Closing comments

Implementing a GUI with App Designer is a rather quick and easy task since it requires little knowledge in programming. Besides, this relies on the well-known MATLAB environment that ACG SDK users are often already familiar with. Also, given the well-integrated UDP communication functions on the B-Box RCP and B-Board PRO platforms, the data exchange is straightforward to set up.

Even though many variables can be sent and read from a remote computer, the main drawback of this approach if the performance because:

  • It relies on executing an interpreted MATLAB code, which is a CPU-intensive task on the PC

  • The UDP handling code processes each RECEIVE request sequentially (i.e. open port, wait for the first incoming packet, transfer data to the user code), which makes this approach inefficient (drops most of the packets) and slow.

Consequently, for use cases where performance is more important than flexibility (e.g. data logging), other solutions should be considered such as for example BB Control software.

  • No labels