Development

.github/workflows/core-baseStation.yml

@@ -1,47 +1,22 @@
-# This is a basic workflow to help you get started with Actions
-
 name: CI - Core - Base Station
 
-# Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the main branch
-  push:
-    branches: [ "**" ]
-    paths:
-      - "software/core/oqm-core-base-station/**"
-      - ".github/workflows/core-baseStation.yml"
-      - ".github/workflows/wf-gradleBuild.yaml"
-      - ".github/workflows/wf-gradleUnitTest.yaml"
-      - ".github/workflows/wf-gradleQuarkusIntTest.yaml"
   pull_request:
-    branches: [ "**" ]
     paths:
       - "software/core/oqm-core-base-station/**"
       - ".github/workflows/core-baseStation.yml"
-      - ".github/workflows/wf-gradleBuild.yaml"
-      - ".github/workflows/wf-gradleUnitTest.yaml"
-      - ".github/workflows/wf-gradleQuarkusIntTest.yaml"
   workflow_call:
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
-defaults:
-  run:
-    working-directory: "software/core/oqm-core-base-station"
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+
+concurrency:
+  group: ci-core-base-station-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  build:
-    uses: ./.github/workflows/wf-gradleBuild.yaml
-    with:
-      path: "software/core/oqm-core-base-station"
-  unitTest:
-    uses: ./.github/workflows/wf-gradleUnitTest.yaml
-    with:
-      path: "software/core/oqm-core-base-station"
-  intTest:
-    uses: ./.github/workflows/wf-gradleQuarkusIntTest.yaml
-    strategy:
-      matrix:
-        containerBased: [ false ] # TODO:: enable true
+  CI-Pipeline:
+    uses: Epic-Breakfast-Productions/ebp-ci/.github/workflows/quarkus-ci-pipeline.yml@main
     with:
       path: "software/core/oqm-core-base-station"
-      containerBased: ${{ matrix.containerBased }}
+      java-version: "25"
+      run-int-tests: true
+      container-based-int-tests: false

.gitignore

@@ -31,3 +31,4 @@ hs_err_pid*
 
 bin/
 target/
+.gradle/

README.md

@@ -2,10 +2,11 @@
 
 # Open QuarterMaster
 
+**Inventory without a catch, and all the hooks**
+
 <!-- https://shields.io -->
 ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/Epic-Breakfast-Productions/OpenQuarterMaster)
 ![GitHub all releases](https://img.shields.io/github/downloads/Epic-Breakfast-Productions/OpenQuarterMaster/total)
-![Core API](https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/actions/workflows/core-api.yml/badge.svg)
 [![Code Triage Open Source Helpers](https://www.codetriage.com/epic-breakfast-productions/openquartermaster/badges/users.svg)](https://www.codetriage.com/epic-breakfast-productions/openquartermaster)
 
 [//]: # (![Station Captain]&#40;https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/actions/workflows/stationCaptain.yml/badge.svg&#41;)
@@ -16,33 +17,57 @@
 [![All Contributors](https://img.shields.io/badge/all_contributors-22-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-**Inventory without a catch, and all the hooks**
+<details>
+<summary>🛠 CI Status 🛠</summary>
+
+## [Core](./software/core)
+
+| Service                                               | Status                                                                                                                            |
+|-------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| [Core API](./software/core/oqm-core-api)              | ![Core API](https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/actions/workflows/core-api.yml/badge.svg)             |
+| [Base Station](./software/core/oqm-core-base-station) | ![Base Station](https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/actions/workflows/core-baseStation.yml/badge.svg) |
+
+## [Plugins](./software/plugins)
+
+| Service                                                         | Status                                                                                                                                        |
+|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| [External Item Search](./software/plugins/external-item-search) | ![External Item Search](https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/actions/workflows/plugin-extItemSearch.yml/badge.svg) |
+| [Storagotchi](./software/plugins/storagotchi)                   | ![Storagotchi](https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/actions/workflows/plugin-storagotchi.yml/badge.svg)            |
+
+</details>
+
 
 Open Quartermaster is an open source inventory management system, designed to be simple to use yet powerful and extendable. The last inventory management system you will ever need!
 
-We are very much in development still, so check back often! We are also accepting any and all assistance, so feel free to report issues or feature requests, as well as pull requests! Additionally, feel free to ask questions in the [Discussions](https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/discussions) or just hang out with us on our [Discord](https://discord.gg/cpcVh6SyNn)
+We are very much in development still, so check back often! We are also accepting any and all assistance, so feel free to report issues or feature requests, as well as pull requests! Additionally, feel free to ask questions in
+the [Discussions](https://github.com/Epic-Breakfast-Productions/OpenQuarterMaster/discussions) or just hang out with us on our [Discord](https://discord.gg/cpcVh6SyNn)
 
 ## Quick Links
 
- - For a quick start running on your own computer, check out [Single Host Deployment](deployment/Single%20Host)
- - To see all the ways you can deploy OQM for yourself, see [Deployment](deployment/)
- - For information on the overall system, see the [software](software/) directory.
+- For a quick start running on your own computer, check out [Single Host Deployment](deployment/Single%20Host)
+- To see all the ways you can deploy OQM for yourself, see [Deployment](deployment/)
+- For information on the overall system, see the [software](software/) directory.
 
 ## How it works
 
-How we accomplish the goal of being the only inventory management system you could ever need is through our modular design. The main component of Open QuarterMaster is the [Core API](software/core/oqm-core-api). Think of this as the central hub and core functionality of the system. It handles all the generic inventory management tasks; what is stored where, and facts about what is stored. This central component is designed to be, on the whole, generic and accessible. We also have a frontend for the core API called the [Base Station](software/core/oqm-core-base-station), which lets you have direct and easy to navigate access to your inventory.
+How we accomplish the goal of being the only inventory management system you could ever need is through our modular design. The main component of Open QuarterMaster is the [Core API](software/core/oqm-core-api). Think of this as the central
+hub and core functionality of the system. It handles all the generic inventory management tasks; what is stored where, and facts about what is stored. This central component is designed to be, on the whole, generic and accessible. We also
+have a frontend for the core API called the [Base Station](software/core/oqm-core-base-station), which lets you have direct and easy to navigate access to your inventory.
 
-To cover specific use-cases, we have what we call [Plugins](software/plugins). These are components that extend the functionality of the basic inventory management, and fill additional needs with their own capabilities. Examples could include Smart Refrigerator integrations, a system for interacting with physical storage mediums, Point of Sale Systems, Workflow management.. the list is endless. You could even create your own!
+To cover specific use-cases, we have what we call [Plugins](software/plugins). These are components that extend the functionality of the basic inventory management, and fill additional needs with their own capabilities. Examples could
+include Smart Refrigerator integrations, a system for interacting with physical storage mediums, Point of Sale Systems, Workflow management.. the list is endless. You could even create your own!
 
-In the theme of flexibility, the system is designed to be run in many different environments. It is just as home on the cloud as well as something as small as a [Raspberry Pi](https://www.raspberrypi.com/). This is accomplished using containers, segmenting each software component, ensuring flexibility and ease of management.
+In the theme of flexibility, the system is designed to be run in many different environments. It is just as home on the cloud as well as something as small as a [Raspberry Pi](https://www.raspberrypi.com/). This is accomplished using
+containers, segmenting each software component, ensuring flexibility and ease of management.
 
 To get started on your own hardware, please see [Single Host Deployment](deployment/Single%20Host)
 
-For more information on the overall system, see the [software](software/) directory. 
+For more information on the overall system, see the [software](software/) directory.
 
 ## On Privacy
 
-Being an open initiative, we take great care to ensure you are in control of your own data. None of the software we include here phones home at all, with the brief exception of Station Captain, which looks to this Git repository for installations and updates. If you have a simple setup on your own hardware, you can expect your data to stay with you, and not transmitted anywhere by the software we include here.
+Being an open initiative, we take great care to ensure you are in control of your own data. None of the software we include here phones home at all, with the brief exception of Station Captain, which looks to this Git repository for
+installations and updates. If you have a simple setup on your own hardware, you can expect your data to stay with you, and not transmitted anywhere by the software we include here.
 
 ## Contributors ✨
 

hardware/speed-scanner/OQM-Scanner-Community-Guide.md

@@ -0,0 +1,142 @@
+# Community Guide - OQM Fast Transaction Scanner
+
+This project provides a hardware-based solution to automate inventory management for the **Open Quarter Master (OQM)** system. It replaces manual web-browser data entry with a standalone physical device that connects via Wi-Fi for real-time updates.
+
+## Table of Contents
+1. [Bill of Materials (BOM)](#bill-of-materials-bom)
+   - [Compatibility Warning](#compatibility-warning)
+   - [Required Hardware Components](#required-hardware-components)
+2. [Hardware Assembly & Pinout](#hardware-assembly--pinout)
+   - [Master Wiring Table](#master-wiring-table)
+3. [Firmware Files Structure](#firmware-files-structure)
+4. [SD Card Configuration](#sd-card-configuration)
+5. [Security Logic](#security-logic)
+6. [Software Installation & Setup](#software-installation--setup)
+   - [Environment Setup](#environment-setup)
+   - [Required Libraries](#required-libraries)
+   - [Flashing the Firmware](#flashing-the-firmware)
+7. [Interface Guide](#interface-guide)
+   - [Startup & Main Menu](#startup--main-menu)
+   - [Quick Mode](#quick-mode)
+   - [Details Mode](#details-mode)
+
+---
+
+## 1. Bill of Materials (BOM)
+
+### Compatibility Warning
+This guide and the accompanying firmware are designed **strictly** for the components listed below. The pin assignments are hardcoded for this specific hardware stack. Using different components may lead to pinout conflicts or driver issues, as the team has not tested alternative hardware configurations.
+
+### Required Hardware Components
+
+| Item | Description | Purpose | Source / Link | Price (Est. USD) |
+| :--- | :--- | :--- | :--- | :--- |
+| **Adafruit Feather ESP32 V2** | Microcontroller with 8MB Flash & Wi-Fi | The "brain" of the device, handling API calls and security. | [Adafruit Store](https://www.adafruit.com/product/5400) | $19.95 |
+| **TFT FeatherWing 3.5"** | 480x320 Color Touchscreen (V2) | Visual interface for database and block selection. | [Adafruit Store](https://www.adafruit.com/product/3651) | $39.95 |
+| **ATOMIC QR-Code Scanner** | 1D/2D scanning module | High-speed data acquisition of product IDs. | [M5Stack Store](https://shop.m5stack.com/products/atom-barcode-scanner-base) | $16.95 |
+| **MicroSD Card** | Any standard MicroSD card (FAT32) | Stores `sdsetup.json` for Wi-Fi and API configuration. | Generic | ~$8.00 |
+| **Jumper Cables (4-pin)** | Female to Female / Female to Male | Connects the ATOMIC scanner to the Feather Pins 20/22. | [DigiKey](https://www.google.com/search?q=https://www.digikey.com/en/products/detail/sparkfun-electronics/CAB-22726/18066531) / [Amazon](https://www.google.com/search?q=https://www.amazon.com/SparkFun-Qwiic-Cable-Female-Jumper/dp/B07S1V8Z7F) | ~$2.00 |
+| **Standard Hook-up Wires** | Basic solid or stranded wires | Necessary for custom soldering of headers and power lines. | [Adafruit](https://www.adafruit.com/product/3894) / [Amazon](https://www.amazon.com/Qwiic-Cable-Female-Jumper-4-pin/dp/B0992PHLBC) | ~$2.00 |
+| **TOTAL** | | | **Approximate Cost per Unit** | **~$88.85** |
+
+### Note on Power Supply (Battery)
+Our current prototype is powered via the USB-C port of the Feather ESP32 for development and testing stability. While the system is designed for portability, a 3.7V Li-Po battery is not included in this core build. We recommend adding one as a future evolution to ensure full warehouse mobility.
+
+---
+
+## 2. Hardware Assembly & Pinout
+
+To ensure the firmware initializes correctly, you must follow this specific hardware configuration. These mappings are defined in `barcode_scanner.ino` and `functions.ino`.
+
+### Master Wiring Table
+
+| Peripheral | Signal Name | Pin on Feather ESP32 V2 | Description |
+| :--- | :--- | :--- | :--- |
+| **ATOMIC Scanner** | UART RX | **Pin 20** | Data sent from Scanner to the ESP32. |
+| **ATOMIC Scanner** | UART TX | **Pin 22** | Commands sent from ESP32 to the Scanner. |
+| **TFT FeatherWing** | TFT_CS | **Pin 15** | Chip Select for the display logic. |
+| **TFT FeatherWing** | TFT_DC | **Pin 33** | Data/Command toggle for the screen. |
+| **TFT FeatherWing** | TFT_RST | **Pin 32** | Hardware Reset for the display. |
+| **Integrated SD Slot** | SD_CS | **Pin 14** | Chip Select for the MicroSD card. |
+| **All Peripherals** | VCC | **3V** | Power supply (Red wire). |
+| **All Peripherals** | GND | **GND** | Common ground (Black wire). |
+
+> [!IMPORTANT]
+> **Soldering Requirement:** You **MUST solder** the headers to connect the TFT FeatherWing to the ESP32 V2 board. The high-speed SPI bus (used for the TFT and SD card) will fail if connections are loose. Friction-fit or "plug-and-play" attempts will cause the screen to fail during initialization.
+
+---
+
+## 3. Firmware Files Structure
+
+To compile the project, you need to include the following files in your Arduino project folder:
+
+* **`oqm_scanner.ino`**: The main entry point. It initializes the hardware (TFT, Scanner, WiFi) and runs the primary loop.  Also contains http functions
+* **`color.h`**: Contains default color definitions.
+* **`scannerUI.ino`**: Handles all graphical rendering for the Sage Green interface, including the "Quick" and "Detail" mode screens.
+
+---
+
+## 4. SD Card Configuration
+
+The scanner is designed to be "zero-code" for configuration. It looks for a file named `sdsetup.json` on the MicroSD card to set up the network and security.
+
+1.  Format your MicroSD card to **FAT32**.
+2.  Copy the provided `sdsetup.json` file to the root directory.
+3.  Fill in your credentials:
+    * **ssid / password**: Your local Wi-Fi.
+    * **oqm-address**: The IP of your OQM Basestation.
+    * **oqm-user / oqm-secret**: Your Keycloak client credentials.
+
+---
+
+## 5. Security Logic
+
+To ensure professional-grade reliability, the firmware includes the following automated safety features:
+
+* **JWT Authentication**: The system handles secure Keycloak authentication. It automatically calculates the token's expiration and performs a refresh when 75% of its lifespan has passed, ensuring the scanner never logs out during a shift.
+* **Scan Buffer**: A mandatory 5-second delay is enforced between successful scans. This prevents accidental duplicate entries and ensures the OQM server has enough time to process and acknowledge the previous transaction.
+* **Modularity**: By using **Pin 14** for the SD card, the system remains modular, allowing users to update Wi-Fi or API settings without ever touching the source code.
+
+---
+
+## 6. Software Installation & Setup
+
+To compile and flash the firmware, follow these steps to prepare your development environment.
+
+### Environment Setup
+* **IDE**: Download and install **Arduino IDE** (version 2.3.8 or higher).
+* **Board Manager**: Install the **ESP32 by Espressif** board package via the Boards Manager.
+* **Selection**: Select **Adafruit ESP32 Feather V2** as your target board.
+
+### Required Libraries
+Open the Library Manager and install the following:
+* **Adafruit GFX & Adafruit HX8357**: Essential for driving the 3.5" TFT display.
+* **M5UnitQRCode**: Used to interface with the ATOMIC barcode module.
+* **ArduinoJson**: Required for parsing `sdsetup.json` and handling OQM API responses.
+* **WiFi & HTTPClient**: Standard ESP32 libraries for network communication.
+
+### Flashing the Firmware
+1.  Connect the Feather ESP32 V2 to your computer via a high-quality USB-C cable.
+2.  Open `barcode_scanner.ino` (this is the main file that links `functions.ino` and `scannerUI.ino`).
+3.  Select the correct COM port and click **Upload**.
+
+---
+
+## 7. Interface Guide
+
+The UI is designed for high visibility in warehouse environments, featuring a clean white interface with **Sage Green** interactive elements.
+
+### Startup & Main Menu
+* **Initialization**: Upon power-up, the device automatically mounts the SD card and loads credentials from `sdsetup.json`.
+* **Database Selection**: Tap the "Choose" button next to "DB" to toggle through available OQM databases.
+* **Block Selection**: Tap "Choose" next to "Block" to define the specific storage area for your transactions.
+
+### Quick Mode
+* **Purpose**: Optimized for fast, repetitive stock changes.
+* **Scanning**: Point the scanner at a barcode. The product name, ID, and current count will appear under the "Last Item" header.
+* **Interaction**: Use the large **[ + ]** and **[ - ]** buttons to instantly increment or decrement stock levels in the OQM system.
+
+### Details Mode
+* **Navigation**: Tap the **[ -> ]** arrow on the main screen to enter Details Mode.
+* **Options**: Select from five transaction types: **Add**, **Sub**, **Checkout**, **Checkin**, or **Set**.
+* **Confirmation**: Adjust the quantity and tap **"Submit"** to trigger the API call.

hardware/speed-scanner/README.md

@@ -4,5 +4,4 @@ This device's goal is to be a low-cost scanner to facilitate fast transactions f
 
 Usecases being to quickly read in groceries brought in from the store, etc. Be a convenient tool and make the ssytem truly streamlined to use.
 
-TODO #1011