Concurrent Lego EV3 Controller

A multi-threaded Java Swing application to manage a Lego EV3 robot concurrently, supporting both physical and simulated environments with automated tasks.

Explore the Documentation »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
   • Features & Key Highlights
2. Lessons Learned
3. Getting Started
   • Prerequisites
   • Installation & Running Locally
4. Usage
5. Contact
6. Acknowledgments

---

About The Project

   
Lego EV3 Robot Architecture Sketch (Left) & Physical Robot Example (Right)

Managing True Concurrency

What makes this project special is the ability to make the robot do multiple things at the exact same time safely. The system provides features such as:

• Manual Control: Moving the robot via GUI buttons.
• Random Automated Movements: Continuously generating and executing random movements.
• Instant Obstacle Avoidance: Constant 50ms monitoring of a touch sensor that immediately intercepts any running command to execute an evasive maneuver.
• Recording & Replaying: Silently capturing every movement across all threads and saving it to a file.

Important

All these features can be turned on simultaneously. To achieve this without chaotic movement or thread crashing, the project uses a highly tuned synchronization system.

   
Main Control GUI (Left) & Recorder/Replay GUI (Right)

This repository contains Concurrent Lego EV3 Controller, an academic project developed from scratch for the Fundamentos de Sistemas Operativos (Operating Systems Fundamentals) course at ISEL (Instituto Superior de Engenharia de Lisboa), in collaboration with Rodrigo Gonçalves.

This is one of the most challenging and complex projects I developed. It showcases concurrent programming by implementing a multi-level synchronization architecture. The primary goal was to coordinate multiple tasks safely, managing a physical or simulated Lego EV3 robot without deadlocks or race conditions. Through custom implementations of the Producer-Consumer pattern, atomic state machines, and hardware-level mutex wrappers, this application fluidly manages multiple graphical interfaces and background tasks in true parallel harmony.

The Lego EV3 & Computer-Robot Model

The Lego Mindstorms EV3 has a modular structure. For this project, the physical robot was configured with two independent front traction wheels and a rear sphere. It supports up to 4 sensors and 4 actuators, connecting to the computer via Bluetooth.

Because the robot has limited processing power, memory, and battery autonomy, it integrates only basic intelligence for survival. To overcome these limitations, this system employs a Computer-Robot Model: the robot acts as a "slave" executing basic functions, while the computer acts as the "brain", remotely commanding all movements and interacting with the exterior world via Bluetooth (with a minimum response time of 100ms).

Note

Detailed Documentation: This repository includes an academic-documentation folder containing excellent, comprehensive, and highly detailed PDF reports (in Portuguese) covering the entire system architecture, UML diagrams, state machines, and testing methodology.

Note

Missing Video Demo: I currently no longer have personal access to the physical Lego EV3 robot used during this course, so a video demonstration could not be recorded. However, you can still fully test the logic locally using the provided Simulated Mode!

(back to top)

---

Built With

• 
• 
• 

Note: All Java code in this project was developed entirely from scratch by us. The 64-bit .jar and native libraries (such as BlueCove and the EV3 base API) were provided by the professor solely to establish the low-level Bluetooth communication with the robot.

(back to top)

---

Features & Key Highlights

• Producer-Consumer Circular Buffer: Thread-safe buffer (size 16) using 3 semaphores to coordinate commands from multiple GUIs without busy-waiting.
• Atomic Obstacle Avoidance: A thread polls the touch sensor every 50ms and atomically executes an evasive maneuver, preempting other threads.
• Robot Object Pooling: Uses reference counting and Java Monitors to safely allocate, share, or isolate robots across different interfaces.
• Responsive Threads: Implements sleepInterruptivel() (checking interrupts every 100ms) to avoid thread freezing and ensure immediate GUI response.
• Hardware Mutex Wrappers: Ensures fair mutual exclusion directly at the hardware layer via a FIFO binary semaphore, preventing thread starvation.
• Transparent Command Recorder: A background task that silently intercepts and records all robot commands to a text file for later reproduction.
• Simulated & Real Modes: Seamlessly switch between a simulated console and a physical Bluetooth EV3 robot via the Strategy pattern.

Producer-Consumer Synchronization Architecture

Full System UML Architecture

Note: This diagram is highly detailed. Click here or open preview/UML_FINAL.png locally in an image viewer to see it in full resolution.

(back to top)

---

Lessons Learned

• Producer-Consumer Pattern: Consolidated knowledge on managing shared circular buffers between multiple producers and a single consumer using semaphores.
• Resource Management: Learned to implement the Object Pool pattern to safely share or isolate limited resources (robots) across different graphical interfaces.
• Responsive Threads: Implemented interruptible sleeps to ensure immediate thread responsiveness when pausing or stopping tasks, completely avoiding busy waiting.
• Hardware Synchronization: Handled race conditions and ensured atomicity in critical sections when interacting directly with the physical robot's actuators.

(back to top)

---

Getting Started

Follow these instructions to set up a local copy of the project on your machine.

Prerequisites

• Java Development Kit (JDK) 8 or higher
• A 64-bit Operating System (required for the provided native libraries)
• (Optional) Lego EV3 Robot with Bluetooth capabilities, equipped with two wheel motors and a touch sensor.

Installation & Running Locally

1. Clone the repository:

   git clone https://github.com/GuilhermeGraca/java-concurrent-robotics.git

2. Navigate to the project directory:

   cd java-concurrent-robotics

3. Compile the project:
   • Windows:

     javac -cp ".;lib/bibliotecas/*" src/*.java

   • Linux/Mac:

     javac -cp ".:lib/bibliotecas/*" src/*.java

4. Run the application: Make sure to point the java.library.path to the folder containing the 64-bit native libraries (.dll or .so) for Bluetooth communication.
   • Windows:

     java -cp "src;lib/bibliotecas/*" -Djava.library.path=lib/bibliotecas App

   • Linux/Mac:

     java -cp "src:lib/bibliotecas/*" -Djava.library.path=lib/bibliotecas App

Need Help? If the setup does not work or you run into issues running the project locally, please feel free to reach out to me (see the Contact section below). I'll be happy to help you get it running!

(back to top)

---

Usage

• Connect to the robot (or select Simulated Mode).
• Use the directional buttons to command the robot manually.
• Activate Movimentos Aleatórios (Random Movements) to let the robot explore autonomously.
• Activate Evitar Obstáculo (Obstacle Avoidance) to make the robot react to touch sensor input.
• Use the Gravador (Recorder) window to save a cool sequence of movements and replay it effortlessly.

(back to top)

---

Contact

Guilherme Graça - LinkedIn - GitHub

Project Link: https://github.com/GuilhermeGraca/java-concurrent-robotics

(back to top)

---

Acknowledgments

• ISEL - Instituto Superior de Engenharia de Lisboa: For providing the academic environment, resources, and the robot hardware required to develop this project.
• Professor Jorge Pais: For the guidance, theoretical foundations, and the base EV3 communication library provided during the Fundamentos de Sistemas Operativos course.
• Rodrigo Gonçalves: For the partnership and collaborative effort in developing this project.

(back to top)