Presentation "Ports-and-Adapters Architecture for Embedded HMIs" at the Embedded Online Conference 2024

When done right, the ports-and-adapters architecture leads to loosely coupled and cohesive components. Each port has at least a test and an implementation adapter, which makes the business domain easily testable. We outsmart Conway’s law by defining the team structure according to the software structure: the inverse Conway manoeuvre.

1. Ports-and-Adapters Architecture Burkhard Stubert For Embedded HMIs

2. Specialist for UX-Defined Devices Mission: Free smart devices from dumb user interfaces Burkhard’s marquee projects include infotainment systems for cars and driver terminals for sugar beet harvesters, forage harvesters and excavators. As a solo consultant, Burkhard enables his customers to build usage-defined devices. He provides subsystems like UI, machine or cloud communication, OTA updates and secure boot on top of custom-built embedded Linux systems. Newsletter: burkhardstubert.substack.com Web: www.embeddeduse.com Mail: [email protected] Burkhard Stubert

3. 1 USB Ports and Adapters 2 Production Perspective Testing Perspective 4 Team Perspective 5 De-Facto Standard 3

4. USB Ports and Adapters Motivation for Ports-and-Adapters Architecture 1

5. USB Ports and Adapters USB Port: standard interface Many USB-to-X adapters Different companies build and test adapters Computer USB Port USB Adapter (W)LAN CAN BLE RS232 LTE/5G USB port hides specific technology from computer

6. Production Perspective When done right, P&A architecture leads to loosely coupled and cohesive components. 2

7. Ports-and-Adapters Architecture: Production Application Core Machine J1939 Machine MQTT Machine Machine Double CANOpen Machine [CAN] [CAN] [Ethernet] Machine UI Acceptance Tests GUI Voice UI Driver [Application Boundary] [Touch, keys] Camera [Ethernet] Accounting Local DB DB Double Accounting [4G/5G] HMI Terminal Application [Voice]

8. Definitions Adapter Port d epends on Adapter communicates with System Adapter interacts with Person Port Interface between 1 Core and N Adapters (N >= 1) Adapter uses or implements a port Core implements business rules (business logic) Product Adapter used in product Test Adapter used for testing only

9. Implications Ports hide technology used in Adapters from Core No code leaking between Core and Adapters Ports make Core I/O-free Great for testing and maintenance Easy to exchange an Adapter in future Core and other Adapters won’t notice Core drives definition of Ports Raises abstraction level of ports Application Core J1939 Machine MQTT Machine CANOpen Machine Machine UI GUI Voice UI Application Core Adapters and Core depend on Ports: Never the other way round! Apply dependency inversion!

10. Application as Modular Monolith Provide Adapters and Core as libraries living in same applica ti on process Libraries always available, plugins only on demand Load adapter on demand at run-time (plugin) Saves memory For rarely used functionality (e.g., OTA update, VNC mirroring) For add-on functionality enabled after payment (e.g., assistance systems) Adapters as Libraries Application Core J1939 Machine Machine UI GUI Accounting Local DB Application Process

11. Application with Services Extract Adapter as service running in its own process Inter-process communication between Service and Application (e.g., DBUS) Service could run on microcontroller in hybrid SoCs like iMX8 Well-suited for safety-critical or real-time services Adapters as Services Application Core Machine Machine Proxy Application Process Service Core Machine Machine Service J1939 Machine Service Process [DBUS] Machine [CAN] Migration path from modular monolith to SOA

12. Testing Perspective Built-in testing gives rise to modular testing strategy. Avoids exponential explosion of system tests. Use I/O-free tests for CI and I/O-based tests for CD. 3

13. Ports-and-Adapters Architecture: Testing Application Core Machine J1939 Machine MQTT Machine Machine Double CANOpen Machine [CAN] [CAN] [Ethernet] Machine UI Acceptance Tests GUI Voice UI Driver [Voice] [Touch, keys] Camera [Ethernet] Accounting Local DB DB Double Accounting [4G/5G] Test Executable(s) [Test Boundary]

14. I/O-Free Acceptance Tests for Core Replace Product by Test Adapters Tests mimic user interaction with application Similar to CLI Port is bad interface, if tests duplicate code from Product Adapter Abstraction level of Port too low (e.g., pass-through interface) Move duplicated code to Core Use I/O-free tests for development Enabled by TDD Develop Core independently of Adapters – in different teams! Application Core Machine Double Machine UI Acceptance Tests Accounting DB Double Accounting

15. I/O-Free Acceptance Tests for Adapters Replace Core by Acceptance Tests Upper Interface: Machine I/O marks boundary to external systems Push I/O down as far as possible Lower Interface: CanBus Interface J1939 Machine CanBus Interface Machine Acceptance Tests CanBus Double Test Executable Use I/O-free tests for development

16. I/O-Based Tests for Adapters Use real I/O (e.g., CAN bus) Run performance, stress, subsystem tests Covers corner-cases. E.g.: Buffer overflows in Linux kernel Wrong configuration of transfer speed Use I/O-based tests for deployment J1939 Machine CanBus Interface Machine Tests Test Executable Use I/O-based tests for deployment Double Executable(s) f or ECU(s) CanBusIF for ECU CanBus Double [CAN]

17. Team Perspective Outsmart Conway’s law by defining the team structure according to the software structure. 4

18. Applying Conway’s Law The software architecture always mirrors the team structure. Conway’s Law Define the software architecture Define team structure as mirror of software architecture Inverse Conway Manoeuvre Map software structure 1:1 to team structure

19. Separate Teams for Adapters and Core Core team defines and owns Ports UI team as primary driver Adapter teams implement Ports Adapter teams build end-to-end solutions Accounting: client and server Machine: J1939 adapters for all ECUs not just HMI ECU Team Responsibilities Core Team UI Team Machine Team Accounting Team

20. Reality Strikes First: Merge UI into Core team Then: Merge Accounting into Core team Avoid merging Machine team Not enough developers for 4 teams Machine Team Extended Core Team

21. Reality Strikes Harder Introduce well-defined interface on comms link Interface defined and owned by Manufacturer Double other end for testing Other end developed externally Supplier Manufacturer Internal Machine Team Extended Core Team [J1939/CAN] External Machine Team

22. De-Facto Standard Start with P&A architecture now and adapt it. 5

23. De-Facto Standard Architecture Avoids many dead ends and detours I have tried most of them 🥵😉 Lots of experience built in Known to be technically sound, meeting needs and delivering value Ports-and-Adapters Architecture Start with Ports-and-Adapters architecture now and adapt it!