GSoC-2025: Final Report

Contributor	Vidhu Sarwal
Organization	BeagleBoard.org
Mentor	Jason Kridner, RobertCNelson, lorforlinux, Anuj Deshpande, Vedant Paranjape, Kumar Abhishek
Project	Update Beagle-Tester for Mainline Testing

Important Links:

• Main Code Repository - Github Link
• Pre GSoC - Project Description and Discussion
• Proposal Link - Proposal
• Project Intro Video - Youtube Link
• Weekly Updates - Forum Thread
• Discord Discussion Link - Discord Project Thread

---

Synopsis

The objective is to enhance the Beagle-Tester framework for BeagleBoard devices by adding mikroBUS support and updating it for mainline kernel testing. This project aims to develop an automated regression test suite for Linux kernel on BeagleBoard hardware, enabling continuous validation within the OpenBeagle CI server. The approach includes developing comprehensive test cases for interfaces such as PWM, ADC, UART, I2C, SPI, and GPIO, integrating automated power cycling capabilities for test farms, building a web interface for real-time monitoring of test results, and optimizing the framework for seamless Buildroot deployment. Key deliverables include an enhanced Beagle-Tester with mikroBUS support, an automated regression testing framework for kernel updates, a GitLab CI pipeline for weekly testing, a modular test farm design with power cycling capabilities, a web-based monitoring interface, and comprehensive documentation with tutorials.

---

Deliverables

• Extend beagle-tester to support cape detection and validation.

• Add mikroBUS ClickID support for automated driver loading and testing.

• Implement HDMI output validation via OpenCV-based test.

• Provide automation hooks and web server for integration into a test farm (barcode detection, logging, reporting).

---

Work Completed

1) Add ClickID Detect, Click_Dispatch and Updated Beagle-Tester

More Details in Pull Request

1.1 Barcode Format Convention

We define two types of barcodes:

• Generic Barcode (Triggers Auto Detection)

  • Format: MKB001
  • Purpose: Initiates automatic detection of connected Click board using ClickID EEPROM.

• Specific ClickID Barcode

  • Format: MKBXXXXXXX (e.g., MKBRCCLICK, MKBTHERMOCLICK)
  • Purpose: Directly invokes test for a known Click board without requiring auto-detection.

2. ClickID Detection (clickid_detect.cpp)

• C++ tool to scan the I2C bus and read ClickID EEPROMs.
• Location: src/clickid_detect.cpp
• Scans /dev/i2c-2, address 0x50
• Reads raw EEPROM contents and outputs ClickID string (e.g., RCCLICK).

3. EEPROM Simulation (simulate_clickid.sh)

• Shell script using i2c-stub to simulate ClickID EEPROM.
• Writes test strings like RCCLICK into virtual EEPROM.

4. beagle-tester.c Modifications

• Added auto-detection handler to re-dispatch test based on MKB001.
• Added ClickID dispatch loop for direct matching via click_dispatch.h.

5. Dispatch Table Implementation

• Defined modular dispatch entries in click_dispatch.h and click_dispatch.c.
• Example entry:

  {"MKBRCCLICK", run_rtc5click_test}

6. Example Test: rtc5click

• Minimal test implementation (rtc5click_test.c).
• Provides placeholder for GPIO/I2C validation logic.

7. Folder Structure

include/  
  click_dispatch.h  
  rtc5click_test.h  
src/  
  beagle-tester.c  
  click_dispatch.c  
  clickid_detect.cpp  
click_tests/  
  rtc5click_test.c  

8. Makefile Updates

• Modular build system for C and C++ sources.
• Targets: beagle-tester, clickid_detect.

9. Running the System

• Auto Test:

  sudo ./beagle-tester MKB001

• Manual Test:

  sudo ./beagle-tester MKBRCCLICK

10. Benefits

• Modular: Easy addition of new Click tests.
• Unified: Works for auto-detection and manual barcodes.
• Clean: Keeps test logic separate from core.

---

2) HDMI Output Validation Test (HDMITEST)

More Details in Pull Request

Overview

The HDMITEST validates HDMI output on supported BeagleBoard platforms. It captures frames from a USB HDMI capture device (usually /dev/video0) using OpenCV and checks for colorful activity (red, green, blue). A detected color pattern confirms that HDMI is working.

Features

• Integrated into the standard test sequence for HDMI-capable boards.
• Can also be run manually via CLI:

  beagle-tester HDMITEST
  beagle-tester HDMITEST -s   # save detected frame

• Captures frames for up to 20 seconds.
• Detects red, green, or blue activity via HSV masks.
• Outputs result with beagle_notice("hdmi", "pass/fail").
• Exit codes: 0 → PASS, 1 → FAIL.

Implementation

• Source: src/hdmi_test.cpp
• Binary: hdmi_test installed to /usr/sbin/hdmi_test
• Libraries: Uses OpenCV (V4L2 backend) to capture from /dev/video0
• Integration: Added to Makefile and included in board test flow

Sample Output

Waiting for colorful activity (for up to 20 seconds)...
Colorful activity detected!
PASS

or

Waiting for colorful activity (for up to 20 seconds)...
Timeout: No color detected in 20 seconds.
FAIL

Notes

• Requires a USB HDMI capture device exposed as /dev/video0.
• Ensure HDMI output shows a colorful test pattern (e.g., SMPTE bars).
• Test is skipped silently on boards without HDMI hardware.

---

3) Live Web Interface for Test Results

More Details in Pull Request

Overview

A lightweight HTTP interface has been added to allow real-time viewing of test results in a browser. It runs alongside the framebuffer and terminal outputs and can be accessed over the local network at:

http://<beagle-ip>:8000

Result Serialization

• Test results are serialized to JSON at:

  /tmp/results.json
  

• Generated after test execution from the test_result struct array.

Static Frontend Assets

• Location: /usr/share/beagle-tester/web/
• Files:
  • index.html — displays results in a table
  • style.css — basic theming
  • app.js — fetches updated results every 2 seconds

Web Server

• Implemented in: src/web_server.c using Mongoose v7.18
• Serves both static files and /results.json.
• Also uses src/mongoose.c as the embedded HTTP server library.
• Compilation:

  gcc src/web_server.c src/mongoose.c -o web_server -lpthread

Web Frontend

• Source location: src/web/
• Installed to: /usr/share/beagle-tester/web/
• Automatically polls /results.json every 2 seconds and updates the table.

Integration with beagle-tester

• Added struct in beagle-tester.c:

  struct test_result {
      char test[64];
      char status[64];
      time_t timestamp;
  };

• Results serialized to /tmp/results.json.
• Web server launched automatically at the end of beagle-tester run:

  system("web_server /tmp/results.json &");

Folder Structure

include/
  web_server.h

src/
  beagle-tester.c
  web_server.c
  mongoose.c/.h
  web/
    index.html
    style.css
    app.js

Running

• Standard:

  sudo beagle-tester <code>

  Generates /tmp/results.json and launches web server.
• Manual:

  sudo ./web_server /tmp/results.json

Benefits

• Real-time monitoring of test results via browser.
• JSON-based integration with external tools.
• Standalone binary decoupled from test runner.
• Works without serial console or framebuffer.

---

4) MQTT Publishing Feature

More Details in Pull Request

• Publishes test results to MQTT broker.
• Controlled via /tmp/beagle_tester.conf.
• Results serialized to /tmp/results.json.
• Source: src/mqtt_publisher.c.
• Uses libmosquitto for broker connection.
• Example config:

  [services]
  enable_mqtt = true
  [broker]
  host = 127.0.0.1
  port = 1883
  topic = beagle/test/results

• Subscribe with:

  mosquitto_sub -h 127.0.0.1 -t "beagle/test/results"

• Benefits:
  • Integrates with dashboards.
  • Portable across boards.

---

5) Buildroot Image automation

More Details in Pull Request

• Automated Buildroot-based OS image build for BeagleBone Black on beagle-tester branch updates or manual triggers.
• Generated bootable sdcard.img with kernel, libraries, and custom beagle-tester package, uploaded as CI artifact for testing and deployment.

Architecture diagram

---

Demo Video

Video Demonstrating functionality of implementation.

---

Work Left / Future Work

• Test Farm Infrastructure: Automated power cycling, CI/CD integration, and remote access.

---