Gui Builder Matlab App Designer

Software resources
MATLAB App Designer
Ethernet communication
Data exchange planning
C/C++ code implementation overview
ACG code implementation overview
Implementation principles in App Designer
- Initialization
- Background processes
- Actions
Closing comments

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

The implementation of such an interface is typically useful in order to manage the run-time execution of a power converter, including for instance:

Status information (running, stopped, discharge, fault, etc.)
Real-time measurements (power flows, voltage, current, etc.)
Fault diagnosis information (log messages, probable causes, etc.)
Operation set points (current, power, etc.)
Commands (start, stop, control mode change, etc.)

The use of such a GUI is often complementary to the imperix remote control software, which is often preferred for debug purposes. Also, the purpose of the GUI is limited to real-time interactions with the power converter controller(s) and is not related to how to program the controller(s), which can be done using dedicated SDKs.

Example of GUI using App Designer — GUI designed with App Designer for the control of a battery-based energy storage system

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.

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. Examples are given in the related Simulink blockset. The present example has been implemented using UDP over Ethernet communication, because of its broad availability.

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/C++ code implementation overview

This section is applicable for users of the imperix CPP SDK.

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); // ... }

Code language: C++ ( cpp )

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);

ACG code implementation overview

This section is applicable for users of the imperix ACG SDK.

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

The Ethernet input mailbox 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 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.

Configuration of the data exchange with the Simulink model

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                          
                          Code language:              Matlab              (              matlab              )

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                          
                          Code language:              Matlab              (              matlab              )

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                          
                          Code language:              Matlab              (              matlab              )

                                                            function                  DCbusreferenceEditFieldValueChanged                  (app, event)                                value = app.DCbusreferenceEditField.Value;                if                app.isconnected     judp('SEND',                2226, app.BBoxIPEditField.Value, flip(typecast(single(value),                'int8'))');                end                end                          
                          Code language:              Matlab              (              matlab              )

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.