1. System Overview

Cranet

Version: 1.0
Platform: ESP32-S3
Category: Network Management & Diagnostics Platform
Architecture: Modular Embedded Controller
Storage: Preferences + external service state
Display: ILI9341 TFT
Development Framework: Arduino Core for ESP32
Programming Language: C++

System Overview
Hardware Architecture
Firmware Architecture
Project Directory Structure
Core System Components
Display User Interface
Button Navigation System
Wi-Fi Management Engine
Ethernet Management
Bluetooth Management
Scanner and Diagnostics
Report Generation System
Settings and Configuration
Menu Framework
System Utilities
Project Resources
Build and Deployment
Troubleshooting
License

1. System Overview

1.1 Introduction

Cranet is a modular network management and diagnostics platform built on the ESP32-S3 microcontroller. It integrates wired networking, wireless communication, network discovery, diagnostics, and a graphical user interface into a single embedded system.

The firmware is designed using a modular object-oriented architecture, where every major subsystem is implemented as an independent software module. This approach improves maintainability, scalability, and code organization while allowing new functionality to be integrated with minimal impact on existing components.

Rather than functioning as a single-purpose network utility, Cranet provides a unified platform capable of managing multiple networking technologies through a consistent graphical interface.

1.2 Purpose

The primary objective of Cranet is to provide a portable embedded platform capable of performing common networking tasks from a single device. The firmware combines Ethernet management, Wi-Fi operations, Bluetooth functionality, network scanning, diagnostics, and report generation within an intuitive menu-driven interface.

By centralizing these capabilities, Cranet simplifies network administration, testing, and troubleshooting without requiring multiple standalone tools.

1.3 Key Features

Ethernet management and diagnostics
Wi-Fi management and monitoring
Bluetooth Low Energy (BLE) support
Network discovery and scanning
Interactive graphical user interface
Menu-driven navigation system
Real-time device status monitoring
Persistent configuration storage
Modular firmware architecture
Integrated report generation

1.4 System Architecture Overview

The firmware follows a layered architecture centered around the CranetApp application controller. During system startup, the application initializes each subsystem before entering the main execution loop, where all user interaction and system updates are coordinated.

Major firmware subsystems include:

Display Manager
Menu Controller
Button Controller
Ethernet Manager
Wi-Fi Manager
Bluetooth Manager
Scanner Manager
Report Manager
Settings Manager
Utility Components

Each subsystem is responsible for a specific functional area while remaining coordinated through the central application controller.

1.5 Startup Sequence

When the firmware starts, the following initialization sequence is performed:

Initialize serial communication
Load persistent settings
Initialize the display subsystem
Initialize button controls
Initialize Ethernet services
Initialize Wi-Fi services
Initialize Bluetooth services
Initialize scanner services
Initialize report management
Initialize the menu system
Display the boot screen
Enter the interactive graphical interface

This initialization process ensures that all hardware and software components are ready before user interaction begins.

1.6 Design Principles

The Cranet firmware is developed around several core design principles:

Modular architecture
Object-oriented implementation
Separation of concerns
Hardware abstraction
Maintainable code structure
Scalable subsystem design
Reusable software components
Responsive graphical interface

These principles provide a robust foundation for future expansion while maintaining a clean and organized codebase.

2. Hardware Architecture

2.1 Hardware Overview

Cranet is built around the ESP32-S3 microcontroller and combines wired networking, wireless communication, a color graphical display, and physical navigation controls into a single embedded platform for network management and diagnostics.

The hardware architecture is designed using a modular approach where each peripheral is managed independently through dedicated firmware components. This separation simplifies maintenance, improves scalability, and allows new hardware features to be integrated with minimal changes to the overall system.

2.2 Core Hardware Components

Component	Description
ESP32-S3	Primary microcontroller responsible for firmware execution, networking, and user interface control
ILI9341 TFT Display	320 × 240 SPI color display used for the graphical user interface
W5500 Ethernet Controller	SPI-based Ethernet controller providing wired network connectivity
Push Button Interface	Six dedicated navigation buttons for interacting with the graphical menu system
Internal Wi-Fi Radio	Integrated 2.4 GHz IEEE 802.11 wireless interface
Bluetooth Low Energy (BLE)	Integrated Bluetooth radio for nearby device discovery
SPI Bus	High-speed communication interface shared between hardware peripherals
Flash Memory	Stores firmware and persistent configuration data

2.3 System Hardware Block Diagram

                    +-----------------------+
                    |       ESP32-S3        |
                    |                       |
                    |  Main MCU & Firmware  |
                    +-----------+-----------+
                                |
        +-----------------------+-----------------------+
        |                       |                       |
        |                       |                       |
+-------v------+       +---------v--------+     +--------v--------+
| ILI9341 TFT  |       | W5500 Ethernet   |     | Navigation      |
| Display      |       | Controller       |     | Buttons         |
+--------------+       +------------------+     +-----------------+
                                |
                                |
                        Wired Ethernet

        +-----------------------+-----------------------+
        |                                               |
+-------v--------+                             +---------v---------+
| Wi-Fi Radio    |                             | Bluetooth LE      |
| (Integrated)   |                             | (Integrated)      |
+----------------+                             +-------------------+

2.4 Display System

The graphical interface is rendered on an ILI9341 TFT display configured with a resolution of 320 × 240 pixels. The display operates over the SPI bus and provides the primary interface for menu navigation, diagnostics, network information, status indicators, and system notifications.

The display subsystem is managed independently by the DisplayManager module.

2.5 Ethernet Interface

Wired networking is provided through a W5500 SPI Ethernet controller.

The Ethernet subsystem supports:

Dynamic (DHCP) addressing
Static IP configuration
Gateway detection
DNS configuration
Link monitoring
ICMP ping diagnostics
Connection status reporting

All Ethernet operations are managed through the dedicated EthernetManager module.

2.6 Wireless Interfaces

The ESP32-S3 provides two integrated wireless communication interfaces.

Wi-Fi

The integrated Wi-Fi radio is used for:

Wireless network scanning
Network monitoring
Connection management
Signal information collection

Bluetooth Low Energy (BLE)

The integrated Bluetooth controller provides:

BLE device discovery
Nearby device scanning
Bluetooth status monitoring

Each wireless subsystem operates independently through its respective firmware manager.

2.7 User Input System

User interaction is performed using six dedicated hardware buttons.

Button	Primary Function
Up	Navigate upward through menus
Down	Navigate downward through menus
Back	Return to the previous screen
Enter	Select or confirm an item
Home	Return to the main dashboard
Function	Execute context-specific actions

The firmware implements software debouncing, long-press detection, and repeat functionality to ensure reliable user input.

2.8 GPIO Configuration

The firmware defines dedicated GPIO assignments for all primary peripherals.

Display Interface

Signal	GPIO
TFT CS	38
TFT DC	36
TFT RESET	37
SPI MOSI	40
SPI MISO	39
SPI SCK	41
SD Card CS	35

Ethernet Interface

Signal	GPIO
W5500 CS	14
W5500 IRQ	10
W5500 RESET	9
SPI MOSI	11
SPI MISO	12
SPI SCK	13

Navigation Buttons

Button	GPIO
Up	1
Down	2
Back	15
Enter	16
Home	17
Function	18

2.9 Hardware Design Philosophy

The hardware architecture is designed around modularity and hardware abstraction. Each peripheral is isolated behind its own firmware interface, allowing the application logic to remain independent of low-level hardware implementation.

This design provides several advantages:

Modular hardware integration
Simplified maintenance
Easier hardware replacement
Independent subsystem development
Improved scalability
Cleaner firmware organization

By separating hardware control from application logic, Cranet maintains a flexible architecture that can accommodate future hardware revisions with minimal impact on the rest of the firmware.

3. Firmware Architecture

3.1 Architecture Overview

The Cranet firmware is implemented using a modular object-oriented architecture that separates hardware control, networking, user interface, diagnostics, and configuration into independent software modules.

Instead of concentrating all functionality inside the Arduino setup() and loop() functions, Cranet delegates application control to a central application controller (CranetApp). This controller coordinates subsystem initialization, user interaction, menu navigation, networking services, diagnostics, and screen rendering throughout the system's execution.

This architecture improves maintainability, scalability, readability, and long-term extensibility of the firmware.

3.2 Firmware Structure

The firmware is divided into multiple independent modules, each responsible for a specific functional area.

Module	Responsibility
`CranetApp`	Central application controller
`DisplayManager`	Graphical rendering and screen management
`MenuController`	Menu hierarchy and navigation
`Buttons`	Hardware button processing
`SettingsManager`	Persistent configuration management
`EthernetManager`	Ethernet communication and diagnostics
`WiFiManager`	Wi-Fi management and monitoring
`BluetoothManager`	Bluetooth Low Energy operations
`ScannerManager`	Network scanning and discovery
`ReportManager`	Diagnostic report generation
`Utils`	Shared helper functions

Each module exposes a well-defined interface while hiding its internal implementation from the rest of the firmware.

3.3 Application Controller

The firmware is centered around the CranetApp class.

CranetApp is responsible for coordinating every subsystem within the firmware. Rather than allowing direct communication between unrelated modules, it serves as the primary control layer responsible for:

Initializing all firmware components
Processing hardware button input
Managing menu navigation
Updating networking subsystems
Coordinating network scans
Managing report generation
Building screen models
Rendering the graphical interface
Synchronizing overall application state

This centralized design reduces coupling between modules and simplifies future development.

3.4 Firmware Initialization Sequence

During system startup, the firmware initializes each subsystem in a defined order.

Power On
    │
    ▼
Serial Initialization
    │
    ▼
Settings Manager
    │
    ▼
Display Manager
    │
    ▼
Button Controller
    │
    ▼
Ethernet Manager
    │
    ▼
Wi-Fi Manager
    │
    ▼
Bluetooth Manager
    │
    ▼
Scanner Manager
    │
    ▼
Report Manager
    │
    ▼
Menu Controller
    │
    ▼
Boot Logo
    │
    ▼
Interactive User Interface

This initialization sequence ensures that all required services are available before user interaction begins.

3.5 Runtime Execution Model

Once initialization is complete, the firmware enters the continuous execution loop.

void loop()
{
    app.update();
}

During every execution cycle, the application controller performs tasks such as:

Reading hardware button states
Processing menu navigation
Updating Ethernet services
Updating Wi-Fi services
Updating Bluetooth services
Monitoring scanner operations
Refreshing diagnostic information
Rendering the current display
Synchronizing user interface state

This centralized update mechanism keeps the firmware responsive while maintaining predictable execution flow.

3.6 Module Interaction

The firmware follows a controller-based communication model.

                 CranetApp
                     │
     ┌───────────────┼────────────────┐
     │               │                │
     ▼               ▼                ▼
 Display        Menu Controller    Buttons
     │
     ▼
 Screen Rendering

     │
     ▼
 Ethernet Manager
 Wi-Fi Manager
 Bluetooth Manager
 Scanner Manager
 Report Manager
 Settings Manager

Subsystems do not directly depend on one another unless required. Instead, the application controller coordinates data exchange and execution order.

3.7 Object-Oriented Design

The firmware is developed using object-oriented programming principles.

Each subsystem is implemented as an independent C++ class responsible for:

Managing its own internal state
Providing a public interface
Encapsulating implementation details
Minimizing dependencies on other modules

This design improves readability while making future expansion significantly easier.

3.8 State Management

The firmware maintains application state through dedicated managers instead of relying on global variables.

Examples include:

Current active view
Selected menu item
Scroll position
Network status
Scanner progress
Bluetooth scan state
Ethernet connection status
Report generation state
Persistent configuration

Keeping state localized improves reliability and reduces unintended side effects between modules.

3.9 Design Principles

The Cranet firmware is designed around several fundamental software engineering principles:

Modular architecture
Object-oriented design
Separation of concerns
Hardware abstraction
Reusable software components
Centralized application control
Independent subsystem management
Scalable firmware organization
Maintainable code structure

These principles provide a stable foundation for future feature development while keeping the firmware organized and easy to maintain.

4. Project Directory Structure

4.1 Directory Overview

The Cranet firmware follows a modular directory structure where each functional subsystem is implemented as an independent pair of C++ source (.cpp) and header (.h) files. This organization separates responsibilities, improves maintainability, and simplifies future development.

The project entry point is the Arduino sketch (cranet.ino), which initializes the application controller responsible for coordinating the remaining firmware modules.

4.2 Project Structure

cranet/
│
├── cranet.ino                 # Arduino application entry point
│
├── App.cpp
├── App.h                      # Main application controller
│
├── Display.cpp
├── Display.h                  # Graphical display management
│
├── Menu.cpp
├── Menu.h                     # Menu navigation system
│
├── Buttons.cpp
├── Buttons.h                  # Hardware button handling
│
├── EthernetManager.cpp
├── EthernetManager.h          # Ethernet management
│
├── WiFiManager.cpp
├── WiFiManager.h              # Wi-Fi management
│
├── BluetoothManager.cpp
├── BluetoothManager.h         # Bluetooth Low Energy management
│
├── Scanner.cpp
├── Scanner.h                 # Network scanning and diagnostics
│
├── ReportManager.cpp
├── ReportManager.h           # Report generation
│
├── Settings.cpp
├── Settings.h                # Persistent configuration
│
├── Utils.cpp
├── Utils.h                   # Shared helper utilities
│
├── CranetConfig.h            # Global hardware and firmware configuration
│
├── CranetTypes.h             # Shared data structures and type definitions
│
└── .gitignore

4.3 Entry Point

The firmware starts execution from the Arduino sketch:

cranet.ino

This file contains the standard Arduino setup() and loop() functions. Rather than implementing application logic directly, it delegates execution to the central CranetApp controller, which manages initialization and runtime operation of the entire firmware.

4.4 Core Application Layer

The application layer coordinates every subsystem within the firmware.

File	Responsibility
`App.cpp`	Implements the primary application controller
`App.h`	Declares the `CranetApp` interface

This layer initializes subsystems, manages application state, processes user interaction, and coordinates runtime execution.

4.5 Hardware Abstraction Layer

Hardware-specific functionality is encapsulated within dedicated manager classes.

Module	Responsibility
`Display`	TFT display rendering and graphical interface
`Buttons`	Physical button input processing
`EthernetManager`	Wired Ethernet communication
`WiFiManager`	Wi-Fi networking and scanning
`BluetoothManager`	Bluetooth Low Energy functionality

Separating hardware control from application logic improves portability and maintainability.

4.6 Service Layer

Higher-level firmware services are implemented independently from hardware-specific modules.

Module	Responsibility
`Scanner`	Network discovery and diagnostics
`ReportManager`	Report generation and management
`Settings`	Persistent configuration storage
`Utils`	Shared utility functions

These services provide reusable functionality throughout the firmware.

4.7 Configuration Files

The firmware includes centralized configuration and shared type definitions.

File	Purpose
`CranetConfig.h`	Hardware configuration, constants, GPIO assignments, and compile-time settings
`CranetTypes.h`	Shared structures, enumerations, and common data types

Keeping configuration centralized allows hardware parameters and shared definitions to be maintained from a single location.

4.8 Modular Design Philosophy

Each subsystem is implemented as an independent C++ module consisting of a header file (.h) and a corresponding implementation file (.cpp).

This modular organization provides several advantages:

Clear separation of responsibilities
Simplified debugging
Improved code readability
Better maintainability
Easier feature expansion
Reduced inter-module dependencies
Improved long-term scalability

The resulting project structure is clean, organized, and well suited for continued firmware development as additional networking features are introduced.

5. Core System Components

5.1 Component Overview

The Cranet firmware is composed of multiple independent software components, each responsible for a specific area of functionality. Rather than combining all logic into a single application, the firmware follows a modular architecture where every subsystem operates through a dedicated manager class coordinated by the central application controller.

This design improves maintainability, simplifies debugging, and allows new features to be integrated without affecting unrelated components.

5.2 Application Controller

Files

App.cpp
App.h

The Application Controller (CranetApp) is the core of the firmware. It coordinates every subsystem throughout the device lifecycle.

Responsibilities

System initialization
Runtime execution
Module coordination
Menu management
Display updates
User interaction
State synchronization

Every major firmware component is initialized and managed through this controller.

5.3 Display Manager

Files

Display.cpp
Display.h

The Display Manager controls the graphical user interface displayed on the ILI9341 TFT screen.

Responsibilities

Screen rendering
Dashboard display
Menu drawing
Status indicators
Dialog rendering
Screen refresh management

It provides the visual interface through which users interact with the device.

5.4 Menu Controller

Files

Menu.cpp
Menu.h

The Menu Controller manages the hierarchical navigation system used throughout the firmware.

Responsibilities

Menu hierarchy
Navigation logic
Item selection
Screen transitions
View management

It acts as the primary interface between user input and application functionality.

5.5 Button Controller

Files

Buttons.cpp
Buttons.h

The Button Controller processes all physical button inputs from the device.

Responsibilities

Button state detection
Debouncing
Navigation events
Long-press handling
Input event generation

These events are forwarded to the application controller for processing.

5.6 Ethernet Manager

Files

EthernetManager.cpp
EthernetManager.h

The Ethernet Manager is responsible for all wired networking functionality.

Responsibilities

Ethernet initialization
Link monitoring
IP configuration
Gateway management
DNS configuration
Network diagnostics
Connection status

This module abstracts all hardware-specific Ethernet operations from the rest of the firmware.

5.7 Wi-Fi Manager

Files

WiFiManager.cpp
WiFiManager.h

The Wi-Fi Manager controls the ESP32-S3 integrated wireless interface.

Responsibilities

Wi-Fi initialization
Network scanning
Connection management
Signal monitoring
Wireless diagnostics
Network information retrieval

All wireless networking operations are handled through this component.

5.8 Bluetooth Manager

Files

BluetoothManager.cpp
BluetoothManager.h

The Bluetooth Manager provides Bluetooth Low Energy (BLE) functionality.

Responsibilities

BLE initialization
Device discovery
Bluetooth scanning
Device information collection
Wireless status management

This module isolates Bluetooth functionality from the remainder of the firmware.

5.9 Scanner Manager

Files

Scanner.cpp
Scanner.h

The Scanner Manager performs network discovery and diagnostic operations.

Responsibilities

Network scanning
Device discovery
Scan management
Diagnostic processing
Scan result collection

It provides the core diagnostic capabilities of the Cranet platform.

5.10 Report Manager

Files

ReportManager.cpp
ReportManager.h

The Report Manager organizes and manages diagnostic output generated by the firmware.

Responsibilities

Report creation
Result storage
Report formatting
Diagnostic summaries
Scan result management

This component centralizes all reporting functionality.

5.11 Settings Manager

Files

Settings.cpp
Settings.h

The Settings Manager provides persistent configuration storage.

Responsibilities

Loading saved settings
Saving configuration
Runtime preferences
Persistent storage management
System configuration

Configuration data remains available across device reboots using non-volatile storage.

5.12 Utility Library

Files

Utils.cpp
Utils.h

The Utility Library contains reusable helper functions shared throughout the firmware.

Responsibilities

Common helper functions
Data conversion
Shared calculations
Formatting utilities
General-purpose support routines

Centralizing these functions reduces code duplication across modules.

5.13 Shared Configuration

The firmware also includes centralized configuration and shared type definitions.

File	Purpose
`CranetConfig.h`	Hardware configuration, GPIO assignments, constants, and compile-time settings
`CranetTypes.h`	Shared structures, enumerations, and common data types

These files provide common definitions that are used across multiple firmware components.

5.14 Component Relationships

The firmware components operate together through a centralized architecture.

                 CranetApp
                      │
      ┌───────────────┼────────────────┐
      │               │                │
      ▼               ▼                ▼
 Display         Menu Controller    Buttons
      │
      ▼
 User Interface

      │
      ▼
 Ethernet Manager
 Wi-Fi Manager
 Bluetooth Manager
 Scanner Manager
 Report Manager
 Settings Manager

      │
      ▼
      Utils

Each component is responsible for a clearly defined area of functionality while remaining coordinated through the central application controller. This architecture minimizes dependencies between modules and provides a scalable foundation for future firmware development.

6. Display User Interface

6.1 User Interface Overview

The Cranet firmware provides a fully graphical user interface designed specifically for the integrated 320 × 240 ILI9341 TFT display. Rather than relying on a serial console or command-line interface, all interaction is performed through an intuitive menu-driven graphical environment.

The display subsystem is implemented by the DisplayManager class, which is responsible for rendering every visual element shown on the screen.

6.2 Display Hardware

The graphical interface is rendered using the following hardware configuration.

Component	Description
Display Controller	ILI9341 TFT LCD
Resolution	320 × 240 pixels
Communication Interface	SPI
Graphics Library	Adafruit GFX
Display Driver	Adafruit ILI9341

The display is initialized during system startup before the application enters the main user interface.

6.3 Display Manager

Files

Display.cpp
Display.h

The DisplayManager class encapsulates all graphical rendering operations performed by the firmware.

Responsibilities

Display initialization
Boot logo rendering
Dashboard rendering
Menu rendering
List rendering
Status badge rendering
Header rendering
Footer rendering
Toast notifications
Screen refresh management

This separation allows the remainder of the firmware to remain independent of display-specific implementation details.

6.4 Boot Screen

During startup, the firmware presents a dedicated boot screen before entering the main application.

The boot screen displays:

Application vendor
Application name
Device category
Platform information
Display information

This provides visual confirmation that the firmware has initialized successfully before transitioning to the main interface.

6.5 Screen Layout

The graphical interface follows a consistent layout across every screen.

+--------------------------------------------------+
| Header                                           |
|  Title      Subtitle          Status Badges      |
+--------------------------------------------------+
|                                                  |
|                                                  |
|             Main Content Area                    |
|                                                  |
|                                                  |
+--------------------------------------------------+
| Footer                                           |
| UP  DOWN  ENTER  BACK  HOME  FUNC      Status    |
+--------------------------------------------------+

This layout provides a predictable user experience regardless of the active menu or feature.

6.6 Header Section

The header occupies the top portion of every screen.

It displays:

Current screen title
Optional subtitle
Network status badges
System indicators

The header provides users with immediate context regarding the active view.

6.7 Content Area

The center of the display is dynamically updated depending on the current application state.

The firmware supports several content layouts, including:

Dashboard view
Menu view
List view
Information view
Status messages

Each screen is rendered using a common ScreenModel, allowing the interface to remain consistent while displaying different information.

6.8 Footer Section

The footer provides navigation guidance and runtime status information.

It displays the available hardware button actions, including:

UP
DOWN
ENTER
BACK
HOME
FUNC

The footer also displays short status messages generated by the application.

6.9 Status Badges

The firmware displays compact status badges within the header to provide quick visibility into subsystem states.

Examples include:

Ethernet status
Wi-Fi status
Bluetooth status
Scanner activity
Other runtime indicators

Badges automatically update as the system state changes.

6.10 Toast Notifications

The display subsystem supports temporary toast notifications.

Toast messages are used to provide immediate user feedback after actions such as:

Configuration changes
Menu operations
Network events
Diagnostic operations
System notifications

Notifications automatically disappear after a predefined timeout without interrupting the current workflow.

6.11 Rendering Pipeline

Screen rendering follows a structured pipeline.

Application State
        │
        ▼
 ScreenModel Generation
        │
        ▼
 DisplayManager::render()
        │
        ▼
 Draw Header
        │
        ▼
 Draw Main Content
        │
        ▼
 Draw Footer
        │
        ▼
 Draw Toast (if active)
        │
        ▼
 Display Updated Screen

This layered rendering process ensures that all screens maintain a consistent appearance throughout the firmware.

6.12 User Interface Design Principles

The graphical interface is designed around several core principles:

Consistent screen layout
Minimal navigation complexity
Clear visual hierarchy
Responsive user feedback
Efficient use of screen space
Reusable rendering components
Separation between application logic and display rendering

These principles provide a responsive and intuitive interface while allowing the display subsystem to remain modular and easily maintainable.

7. Button Navigation System

7.1 Overview

The Cranet firmware uses a dedicated hardware button interface for all user interaction. Instead of relying on touch input or serial commands, the graphical user interface is controlled entirely through six physical navigation buttons.

The button subsystem is implemented in the Buttons module, which provides reliable input processing through software debouncing, long-press detection, and automatic key repeat functionality.

7.2 Button Controller

Files

Buttons.cpp
Buttons.h

The Buttons class serves as the central interface between the physical buttons and the rest of the firmware.

Responsibilities

Button initialization
Input polling
Event generation
Debouncing
Long-press detection
Auto-repeat handling
Button state management

The application controller reads all user input through this module rather than accessing GPIO pins directly.

7.3 Navigation Buttons

The firmware defines six dedicated navigation buttons.

Button	Primary Function
Up	Move the selection upward
Down	Move the selection downward
Back	Return to the previous screen
Enter	Select or confirm an option
Home	Return to the main interface
Function	Execute context-specific operations

These buttons provide a consistent navigation experience across every screen within the firmware.

7.4 Input Processing

Each hardware button is represented internally by an independent DebouncedButton object.

The firmware continuously monitors button states and converts electrical signals into application events.

Supported events include:

Button press
Button release
Button hold
Automatic repeat
Continuous pressed state

This event-driven approach simplifies interaction with the remainder of the firmware.

7.5 Software Debouncing

Mechanical push buttons naturally produce rapid signal fluctuations when pressed or released.

To eliminate false triggers, the firmware implements software debouncing.

Debounce Characteristics

Parameter	Value
Debounce Time	30 ms
Input Type	Active-Low
Detection Method	Stable state verification

Only stable input transitions are accepted as valid button events.

7.6 Long-Press Detection

The firmware distinguishes between a normal button press and a long press.

A long-press event is generated only after the button remains continuously pressed beyond the configured threshold.

Parameter	Value
Hold Time	700 ms

Long-press events are generated only once per press cycle.

7.7 Automatic Key Repeat

The Up and Down navigation buttons support automatic repeat to improve navigation through long menus.

After the initial hold period, repeated navigation events are generated automatically until the button is released.

Parameter	Value
Initial Repeat Delay	700 ms
Repeat Interval	120 ms

This behavior enables efficient scrolling without requiring repeated button presses.

7.8 Button State Model

Each button maintains its own runtime state.

The firmware tracks:

Current pressed state
Previous stable state
Raw GPIO state
Press event
Release event
Long-press event
Repeat event
Press timestamp
Next repeat timestamp

Maintaining independent state information for every button improves responsiveness and prevents interference between simultaneous inputs.

7.9 Button Processing Workflow

The input processing sequence is performed during every firmware update cycle.

Read GPIO State
        │
        ▼
Software Debounce
        │
        ▼
State Change Detection
        │
        ▼
Generate Events
        │
        ├───────────────┐
        │               │
        ▼               ▼
 Normal Press     Long Press
        │               │
        └───────┬───────┘
                ▼
        Auto Repeat Check
                │
                ▼
      Forward Event to App

This workflow ensures reliable event generation while minimizing false button activations.

7.10 Integration with the Firmware

The Buttons module operates as an independent subsystem.

During each application update cycle:

Button states are sampled.
Input events are generated.
The application controller processes the events.
The menu system updates the current selection.
The display refreshes to reflect the new interface state.

This architecture cleanly separates hardware input processing from application logic.

7.11 Design Principles

The button navigation system is designed around the following principles:

Reliable hardware input detection
Event-driven architecture
Software debouncing
Long-press support
Automatic key repeat
Independent button state management
Modular implementation
Separation between hardware input and application logic

These principles provide a responsive and consistent navigation experience throughout the Cranet firmware.

8. Wi-Fi Management Engine

8.1 Overview

The Wi-Fi Management Engine is responsible for all IEEE 802.11 wireless networking functionality within the Cranet firmware. It provides wireless network discovery, connection management, saved network profiles, monitor mode support, packet statistics, and real-time status reporting through a unified software interface.

All Wi-Fi functionality is encapsulated within the WiFiManager class, ensuring that wireless operations remain isolated from the remainder of the firmware.

8.2 Module Information

Files

WiFiManager.cpp
WiFiManager.h

The module is initialized during system startup and remains active throughout the firmware lifecycle.

Responsibilities

Wi-Fi initialization
Wireless network scanning
Saved network management
Connection handling
Network sorting
Monitor mode
Packet statistics
Runtime status monitoring

8.3 Initialization

During firmware startup, the Wi-Fi Manager performs the following tasks:

Initializes the ESP32-S3 Wi-Fi subsystem
Configures Station (STA) mode
Disables Wi-Fi sleep mode
Restores current connection state
Registers the settings manager

This prepares the wireless subsystem before the graphical interface becomes available.

8.4 Wi-Fi Scanning

The firmware supports asynchronous wireless network scanning.

During a scan, the ESP32-S3 disconnects from any active network and performs a full scan of nearby access points.

Each discovered network records:

SSID
Hidden network status
BSSID (MAC Address)
Vendor information
RSSI (Signal Strength)
Operating channel
Security type

Scan results are automatically stored and made available to the graphical interface after completion.

8.5 Network Information

Each discovered wireless network contains the following information.

Property	Description
SSID	Wireless network name
Hidden	Indicates whether the SSID is hidden
BSSID	Access point MAC address
Vendor	Manufacturer identified from the MAC address
RSSI	Received Signal Strength Indicator
Channel	Operating Wi-Fi channel
Security	Authentication and encryption type

The firmware automatically replaces empty SSIDs with <hidden> to identify hidden wireless networks.

8.6 Scan Result Sorting

The Wi-Fi Manager supports multiple sorting methods for discovered networks.

RSSI Mode

Networks are sorted by signal strength (highest to lowest).

When two networks have identical signal strength, the operating channel is used as a secondary sorting criterion.

Channel Mode

Networks are grouped according to their operating channel.

Within the same channel, networks are sorted according to signal strength.

This allows users to analyze channel utilization more effectively.

8.7 Saved Network Profiles

The firmware supports persistent storage of Wi-Fi credentials.

Saved profiles are managed through the SettingsManager and allow users to reconnect without re-entering credentials.

Supported operations include:

Save current network
Connect to saved network
Delete saved profile

Profiles are retained across system reboots using non-volatile storage.

8.8 Connection Management

The Wi-Fi Manager provides basic wireless connection control.

Supported operations include:

Connect to saved profile
Disconnect from current network
Update connection status
Monitor active connection

Runtime status messages indicate whether the device is:

Connected
Disconnected
Scanning
Operating in Monitor Mode

8.9 Monitor Mode

The firmware supports IEEE 802.11 monitor mode using the ESP32-S3 promiscuous packet interface.

When monitor mode is enabled:

Station mode remains active
Promiscuous packet capture is enabled
Raw wireless traffic is processed
Packet statistics are updated continuously

Monitor mode can be enabled or disabled directly through the Wi-Fi Manager.

8.10 Packet Statistics

While monitor mode is active, the firmware classifies captured packets into multiple categories.

Packet Type	Description
Management	Beacon, Probe, Association, Authentication, and other management frames
Data	Wireless data traffic
Control	IEEE 802.11 control frames

The firmware maintains independent counters for each packet type and provides a summarized runtime report.

8.11 Runtime Status

The Wi-Fi subsystem continuously maintains a status string describing its current operating state.

Possible states include:

Connected
Disconnected
Scanning
Monitor Mode

These status messages are displayed throughout the graphical interface to provide immediate feedback regarding wireless activity.

8.12 Wi-Fi Workflow

Initialize Wi-Fi
        │
        ▼
Station Mode
        │
        ▼
Start Scan
        │
        ▼
Discover Networks
        │
        ▼
Collect Network Information
        │
        ▼
Sort Results
        │
        ▼
Display Scan Results
        │
        ▼
User Action
        │
 ┌──────┴─────────┐
 │                │
 ▼                ▼
Connect      Monitor Mode
 │                │
 ▼                ▼
Status       Packet Capture
 │                │
 └──────┬─────────┘
        ▼
Update User Interface

8.13 Design Principles

The Wi-Fi Management Engine is designed around the following principles:

Modular implementation
Asynchronous network scanning
Persistent profile management
Flexible sorting mechanisms
Real-time status monitoring
IEEE 802.11 monitor mode support
Packet statistics collection
Separation of wireless functionality from application logic

This architecture provides a scalable and maintainable wireless networking subsystem while keeping the remainder of the firmware independent of low-level Wi-Fi operations.

9. Ethernet Management

9.1 Overview

The Ethernet Management subsystem provides wired networking capabilities through the W5500 SPI Ethernet controller. It is responsible for interface initialization, network configuration, connection monitoring, DHCP management, static IP configuration, DNS management, and network diagnostics.

All Ethernet functionality is encapsulated within the EthernetManager class, providing a clean abstraction between the hardware interface and the rest of the firmware.

9.2 Module Information

Files

EthernetManager.cpp
EthernetManager.h

The Ethernet Manager is initialized during firmware startup and continuously updates network status throughout system operation.

Responsibilities

Ethernet initialization
W5500 controller management
DHCP management
Static IP configuration
Link status monitoring
DNS management
Gateway detection
Connection state monitoring
Network diagnostics
ICMP ping operations

9.3 Initialization Process

During startup, the Ethernet Manager performs the following operations:

Loads the configured hostname.
Registers network event callbacks.
Initializes the SPI interface.
Starts the W5500 Ethernet controller.
Applies static network configuration if enabled.
Waits for Ethernet events.
Updates runtime network information.

If initialization fails, the subsystem reports the failure while allowing the remainder of the firmware to continue operating.

9.4 Network Configuration

The firmware supports both Dynamic Host Configuration Protocol (DHCP) and Static IP Configuration.

DHCP Mode

When DHCP mode is enabled, the network automatically obtains:

IP Address
Gateway
Subnet Mask
DNS Servers

The firmware also supports renewing or releasing the DHCP lease directly through the Ethernet Manager.

Static Mode

When static configuration is enabled, the following parameters are applied manually:

IP Address
Gateway
Subnet Mask
Primary DNS
Secondary DNS

These settings are loaded from the persistent configuration stored by the SettingsManager.

9.5 Network Status Monitoring

The Ethernet Manager continuously monitors the state of the wired interface.

Runtime information includes:

Property	Description
Hostname	Configured device hostname
IP Address	Current IPv4 address
Gateway	Active default gateway
Subnet Mask	Current subnet mask
Primary DNS	DNS Server 1
Secondary DNS	DNS Server 2
MAC Address	Ethernet hardware address
Link Speed	Negotiated Ethernet speed
Link State	Current physical link status
Connection Status	Current network connection state

The firmware periodically refreshes this information while the Ethernet interface remains active.

9.6 Ethernet Events

The firmware responds automatically to Ethernet events generated by the ESP32 networking stack.

Supported events include:

Ethernet Start
Cable Connected
IP Address Assigned
IP Address Lost
Cable Disconnected
Ethernet Stopped

Each event updates the internal network snapshot, ensuring that the graphical interface always displays the current connection state.

9.7 Connection States

The Ethernet subsystem reports several runtime connection states.

State	Description
Idle	Ethernet initialized but inactive
Starting	Interface initialization in progress
Link Up	Physical cable detected
Connected	Network operational with valid IP address
Link Up / Waiting IP	Physical connection established while awaiting IP assignment
Lost IP	Previously assigned address is no longer valid
Disconnected	Ethernet cable disconnected
Offline	Ethernet subsystem inactive
Released	DHCP lease released

These states are continuously updated and displayed within the user interface.

9.8 Network Diagnostics

The Ethernet Manager includes integrated network diagnostic functionality using ICMP Echo Requests (Ping).

The firmware can perform connectivity tests against:

Default Gateway
Google DNS (8.8.8.8)
Cloudflare DNS (1.1.1.1)

Each diagnostic operation records:

Target Host
Success or Failure
Round-trip Time (RTT)
Packet Statistics
Response Duration

Diagnostic results are presented within the graphical interface and stored in the runtime network snapshot.

9.9 Runtime Update Cycle

The Ethernet subsystem operates continuously during firmware execution.

Initialize Ethernet
        │
        ▼
Load Configuration
        │
        ▼
Start W5500 Controller
        │
        ▼
Wait for Network Events
        │
        ▼
Refresh Network Snapshot
        │
        ▼
Update Connection Status
        │
        ▼
Process Ping Requests
        │
        ▼
Update User Interface

The network snapshot is refreshed periodically to ensure that all displayed information remains synchronized with the current network state.

9.10 Integration with Other Components

The Ethernet Manager communicates with several core firmware components.

Component	Purpose
`SettingsManager`	Stores and retrieves Ethernet configuration
`DisplayManager`	Displays Ethernet status information
`MenuController`	Provides user access to Ethernet features
`ReportManager`	Uses diagnostic results for reporting
`CranetApp`	Coordinates runtime execution

This modular integration ensures that networking functionality remains independent while still interacting seamlessly with the remainder of the firmware.

9.11 Design Principles

The Ethernet Management subsystem is designed around several key principles:

Modular architecture
Hardware abstraction
Event-driven networking
Automatic status synchronization
Support for DHCP and static addressing
Integrated network diagnostics
Periodic runtime updates
Separation between networking and application logic

These principles provide a reliable, maintainable, and extensible Ethernet subsystem capable of supporting future networking enhancements.

10. Bluetooth Management

10.1 Overview

The Bluetooth Management subsystem provides Bluetooth Low Energy (BLE) functionality for the Cranet firmware. It is responsible for initializing the Bluetooth stack, discovering nearby BLE devices, collecting advertisement data, identifying device vendors, and maintaining a synchronized list of discovered devices for presentation within the graphical user interface.

All Bluetooth functionality is encapsulated within the BluetoothManager class, providing a clean abstraction between the ESP32-S3 Bluetooth stack and the remainder of the firmware.

10.2 Module Information

Files

BluetoothManager.cpp
BluetoothManager.h

The Bluetooth Manager is initialized during firmware startup and remains available throughout the firmware lifecycle.

Responsibilities

BLE initialization
Device discovery
Advertisement processing
Background scanning
Device information collection
Vendor identification
Runtime status monitoring
Scan result management

10.3 Bluetooth Initialization

During firmware startup, the Bluetooth subsystem performs the following operations:

Initializes the ESP32-S3 BLE stack.
Creates the Bluetooth device instance (CRANET).
Obtains the BLE scan object.
Registers advertisement callbacks.
Configures active scanning mode.
Configures scan interval and scan window.
Creates synchronization resources for thread-safe access.

After initialization, the subsystem enters the Bluetooth Idle state until a scan is requested.

10.4 BLE Device Scanning

The firmware supports active Bluetooth Low Energy device discovery.

When a scan is started, the Bluetooth Manager:

Clears previous scan results.
Starts a background scanning task.
Receives advertisement packets from nearby BLE devices.
Processes each discovered device.
Updates the graphical interface with scan progress.

The scan duration is configurable, with a default duration of 5 seconds.

10.5 Background Scan Task

Bluetooth scanning is performed in a dedicated FreeRTOS task.

Start Scan Request
        │
        ▼
Create Scan Task
        │
        ▼
Start BLE Scan
        │
        ▼
Receive Advertisement Packets
        │
        ▼
Process Each Device
        │
        ▼
Store Device Information
        │
        ▼
Finish Scan
        │
        ▼
Update Runtime Status

Running scans in a background task prevents the graphical interface from becoming unresponsive during device discovery.

10.6 Device Information Collection

For every discovered BLE device, the firmware records the following information.

Property	Description
Device Name	Advertised Bluetooth name (if available)
MAC Address	Unique Bluetooth device address
RSSI	Received Signal Strength Indicator
Service UUID	Primary advertised service UUID (if available)
Manufacturer Data	Raw manufacturer advertisement data (hexadecimal)
Vendor	Vendor identified from the device MAC address
BLE Support	Indicates Bluetooth Low Energy device
Classic Bluetooth	Indicates Classic Bluetooth support (currently not used)

If a device does not advertise a name, the MAC address is used as the display identifier.

10.7 Advertisement Processing

The Bluetooth Manager processes every received advertisement packet through a dedicated callback.

During processing, the firmware:

Extracts the Bluetooth address.
Reads the advertised device name.
Retrieves the RSSI value.
Detects available service UUIDs.
Reads manufacturer-specific advertisement data.
Converts manufacturer data into hexadecimal format.
Identifies the hardware vendor using the device MAC address.
Stores the completed device record.

All discovered devices are maintained in an internal collection for later retrieval.

10.8 Vendor Identification

The firmware performs vendor identification using the Organizationally Unique Identifier (OUI) portion of the Bluetooth MAC address.

For each discovered device:

The MAC address is parsed.
The first three bytes (OUI) are extracted.
The OUI is matched against the internal vendor database.
The corresponding manufacturer name is assigned.

If no match is found, the vendor is reported as Unknown.

10.9 Runtime Status

The Bluetooth subsystem maintains a runtime status string describing its current operating state.

Typical status values include:

Status	Description
Bluetooth Idle	No scan currently running
BLE Scan Running	Device discovery is in progress
BLE Devices: n	Scan completed with discovered device count

The status is updated automatically as scan operations begin and finish.

10.10 Thread Safety

Bluetooth scan results are accessed from multiple execution contexts.

To prevent concurrent modification of the discovered device list, the firmware protects all shared data using a FreeRTOS mutex.

This synchronization mechanism ensures:

Safe background updates
Consistent device snapshots
Reliable GUI rendering
Protection against race conditions

10.11 Integration with Other Components

The Bluetooth Manager operates together with several core firmware components.

Component	Purpose
`CranetApp`	Coordinates Bluetooth operations
`DisplayManager`	Displays discovered devices and runtime status
`MenuController`	Provides access to Bluetooth functions
`SettingsManager`	Supplies runtime configuration
`Utils`	Performs vendor identification and helper operations

The Bluetooth subsystem remains independent while integrating seamlessly with the remainder of the firmware.

10.12 Design Principles

The Bluetooth Management subsystem is designed around the following principles:

Modular architecture
Background BLE scanning
Active device discovery
Thread-safe data management
Automatic vendor identification
Real-time status reporting
Clean separation between Bluetooth operations and application logic
Scalable implementation for future Bluetooth features

This architecture provides an efficient and maintainable Bluetooth subsystem while ensuring responsive operation of the overall Cranet firmware.

11. Scanner and Diagnostics

11.1 Overview

The Scanner and Diagnostics subsystem provides network discovery, host analysis, connectivity testing, service detection, and diagnostic utilities for the Cranet firmware. It combines multiple network analysis tools into a single interface, allowing users to inspect devices on the local network and verify network connectivity.

All scanning and diagnostic operations are implemented by the ScannerManager class, which operates independently while integrating with the Ethernet and Wi-Fi subsystems.

11.2 Module Information

Files

Scanner.cpp
Scanner.h

Responsibilities

Local subnet scanning
Host discovery
Port scanning
ICMP ping diagnostics
TCP connectivity testing
HTTP/HTTPS testing
DNS lookup
Traceroute diagnostics
Device information collection
Diagnostic result management

11.3 Scanner Initialization

During firmware startup, the Scanner Manager is initialized after the networking subsystems.

Initialization includes:

Registering the Ethernet Manager.
Registering the Wi-Fi Manager.
Clearing previous scan results.
Resetting diagnostic data.
Setting the scanner status to Scanner Ready.

Once initialized, the subsystem remains available throughout firmware execution.

11.4 Network Discovery

The Scanner Manager supports automatic discovery of hosts within the local subnet.

When a subnet scan begins, the firmware:

Clears previous scan results.
Determines the active network address.
Iterates through available host addresses.
Tests host availability.
Collects device information.
Stores discovered hosts.

Discovered devices are presented through the graphical interface after the scan completes.

11.5 Host Information Collection

Each discovered host is represented by an internal IpHostInfo structure.

The firmware attempts to collect:

Property	Description
IP Address	IPv4 address of the device
Host Name	Resolved hostname (when available)
MAC Address	Hardware MAC address
Vendor	Manufacturer identified from the MAC address
Open Ports	Detected common TCP ports
Device Status	Online or offline state
Camera Candidate	Indicates whether the host appears to be a network camera based on detected services

This information provides users with a quick overview of devices connected to the network.

11.6 Port Scanning

The Scanner Manager includes a lightweight TCP port scanner for identifying commonly used network services.

When a port scan is requested:

The selected target host is scanned.
Common TCP service ports are tested.
Open ports are recorded.
A summary of detected services is generated.

If ports commonly associated with IP cameras (such as 554, 8000, 8080, or 37777) are detected, the host is flagged as a potential camera device.

11.7 Network Diagnostic Tools

The firmware provides several built-in diagnostic utilities.

ICMP Ping

Performs an ICMP Echo Request to verify host reachability.

Collected information includes:

Target address
Success or failure
Round-trip time (RTT)

TCP Connectivity Test

Attempts to establish a TCP connection with a specified host and port.

This test is useful for verifying whether a particular service is reachable.

HTTP / HTTPS Test

The firmware can send HTTP or HTTPS requests to remote hosts to verify web service availability.

Supported protocols include:

HTTP
HTTPS

DNS Lookup

Performs hostname resolution using the configured DNS server.

This diagnostic verifies that domain name resolution is functioning correctly.

Traceroute Diagnostic

Provides a simplified traceroute diagnostic for identifying the path to a remote destination and assisting with connectivity troubleshooting.

11.8 Runtime Status

The Scanner Manager maintains a runtime status string describing the current operation.

Typical states include:

Status	Description
Scanner Idle	No operation in progress
Scanner Ready	Initialized and ready
Scanning Subnet	Discovering hosts
Port Scan Complete	Port scan finished
Diagnostic Complete	Selected network tool completed

The status is updated automatically throughout each operation.

11.9 Scan Workflow

Initialize Scanner
        │
        ▼
Determine Active Network
        │
        ▼
Subnet Discovery
        │
        ▼
Identify Reachable Hosts
        │
        ▼
Collect Device Information
        │
        ▼
Optional Port Scan
        │
        ▼
Generate Diagnostic Results
        │
        ▼
Display Results

This workflow provides a structured approach to network discovery while keeping the user interface responsive.

11.10 Integration with Other Components

The Scanner Manager operates in conjunction with several core firmware modules.

Component	Purpose
`EthernetManager`	Provides active Ethernet network information
`WiFiManager`	Provides wireless network information
`DisplayManager`	Displays scan progress and results
`MenuController`	Allows users to launch scanner tools
`ReportManager`	Stores diagnostic summaries
`CranetApp`	Coordinates scanner execution

This modular design allows diagnostic functionality to remain independent while integrating seamlessly with the overall firmware architecture.

11.11 Design Principles

The Scanner and Diagnostics subsystem is designed around the following principles:

Modular implementation
Non-blocking diagnostic operations
Multiple integrated network tools
Automatic host discovery
Common service detection
Real-time diagnostic reporting
Clean separation between networking and diagnostics
Scalable architecture for future analysis features

These principles provide a flexible and maintainable diagnostic framework capable of supporting future networking and troubleshooting enhancements.

12. Report Generation System

12.1 Overview

The Report Generation System consolidates information collected from multiple firmware subsystems into a single in-memory diagnostic report. Rather than generating reports independently within each module, the firmware centralizes report creation through the ReportManager, allowing system information, network status, and diagnostic results to be presented in a unified format.

The generated report serves as a snapshot of the device's current operational state and is designed to support future export functionality.

12.2 Module Information

Files

ReportManager.cpp
ReportManager.h

Responsibilities

Build diagnostic reports
Collect subsystem information
Aggregate network status
Summarize scan results
Generate timestamp information
Prepare reports for future SD card export

12.3 Report Manager

The ReportManager coordinates report generation by collecting information from multiple firmware components.

During initialization, it registers references to:

Settings Manager
Ethernet Manager
Wi-Fi Manager
Bluetooth Manager
Scanner Manager

This allows the report generator to access the latest runtime information from each subsystem whenever a report is requested.

12.4 Report Generation Process

When report generation is requested, the firmware performs the following sequence:

Clears the previous report.
Creates a new report document.
Generates a timestamp.
Collects system configuration.
Retrieves Ethernet information.
Retrieves Wi-Fi information.
Retrieves Bluetooth information.
Retrieves scanner information.
Includes the latest diagnostic tool result (if available).
Stores the completed report in memory.

The report remains available until another report is generated.

12.5 Report Structure

Each report consists of structured metadata together with a collection of diagnostic items.

Report Metadata

Field	Description
Title	Report title
Subtitle	Report description
Generated Time	Timestamp or system uptime
Footer	Additional report information

Each report item contains:

Title
Value
Detail
Display state
Accent color

This structure allows the graphical interface to present report information consistently.

12.6 Report Contents

The generated report includes information collected from multiple firmware subsystems.

Typical report entries include:

Information	Source
Device Name	Firmware configuration
Firmware Vendor	Application metadata
Firmware Version	Application metadata
Generation Time	System clock or uptime
Hostname	Settings Manager
Theme	Settings Manager
Display Brightness	Settings Manager
Language	Settings Manager
Ethernet Status	Ethernet Manager
Gateway	Ethernet Manager
Subnet Mask	Ethernet Manager
DNS Servers	Ethernet Manager
MAC Address	Ethernet Manager
Wi-Fi Status	Wi-Fi Manager
Saved Wi-Fi Profiles	Settings Manager
Bluetooth Status	Bluetooth Manager
Scanner Status	Scanner Manager
Discovered Wi-Fi Networks	Wi-Fi Manager
BLE Device Count	Bluetooth Manager
Network Host Count	Scanner Manager

If a diagnostic tool has recently been executed, its latest result is also appended to the report.

12.7 Timestamp Generation

When a real-time clock is available, the report records the generation date and time.

If valid system time has not yet been synchronized, the firmware automatically falls back to recording the device uptime instead.

This ensures that every generated report contains meaningful timing information regardless of network time availability.

12.8 Report Workflow

Generate Report Request
          │
          ▼
Clear Previous Report
          │
          ▼
Create Report Document
          │
          ▼
Collect Settings
          │
          ▼
Collect Ethernet Status
          │
          ▼
Collect Wi-Fi Status
          │
          ▼
Collect Bluetooth Status
          │
          ▼
Collect Scanner Results
          │
          ▼
Append Diagnostic Results
          │
          ▼
Finalize Report
          │
          ▼
Store Report in Memory

This workflow ensures that each report represents a consistent snapshot of the current system state.

12.9 Future Export Support

The current implementation generates reports entirely in memory.

The report footer indicates that the report format has been prepared for future SD card export functionality, allowing generated diagnostic reports to be written to external storage in future firmware releases without requiring changes to the report generation logic.

12.10 Integration with Other Components

The Report Manager collects information from several firmware modules.

Component	Purpose
`SettingsManager`	Device configuration and preferences
`EthernetManager`	Ethernet status and network information
`WiFiManager`	Wireless status and network statistics
`BluetoothManager`	BLE device information
`ScannerManager`	Scanner status and diagnostic results
`CranetApp`	Coordinates report generation

This centralized approach ensures that all diagnostic information is collected consistently.

12.11 Design Principles

The Report Generation System is designed around the following principles:

Centralized report generation
Unified diagnostic snapshots
Modular subsystem integration
Structured report formatting
Timestamped system reports
In-memory report storage
Future-ready export architecture
Separation between data collection and presentation

These principles provide a flexible reporting framework that can be extended to support additional export formats and storage mechanisms in future versions of the Cranet firmware.

13. Settings and Configuration

13.1 Overview

The Settings and Configuration subsystem provides centralized management of all persistent firmware settings within the Cranet platform. It is responsible for loading, storing, updating, and maintaining device configuration using the ESP32-S3's non-volatile storage.

Rather than allowing each subsystem to manage its own configuration independently, Cranet centralizes configuration management through the SettingsManager, ensuring consistency across the entire firmware.

13.2 Module Information

Files

Settings.cpp
Settings.h

Responsibilities

Initialize persistent storage
Load default configuration
Save runtime settings
Manage Ethernet configuration
Manage Wi-Fi profiles
Store user preferences
Maintain system-wide configuration

13.3 Persistent Storage

The firmware uses the ESP32 Preferences library to store configuration data in non-volatile flash memory.

During startup, the SettingsManager opens the cranet preferences namespace and loads all previously stored configuration values.

If a setting is unavailable, the firmware automatically falls back to its default value.

This ensures that configuration persists across device restarts while providing sensible defaults for first-time initialization.

13.4 Configuration Categories

The configuration subsystem manages several independent groups of settings.

Category	Description
Device Settings	General firmware configuration
Ethernet Settings	Static network configuration and DHCP selection
Wi-Fi Profiles	Saved wireless network credentials
Display Settings	Brightness and theme selection
System Settings	Language and diagnostic preferences

13.5 Device Configuration

General firmware configuration includes:

Setting	Purpose
Hostname	Device hostname used for network identification
Language	User interface language
Ping Target	Default target used for network diagnostics
Theme	User interface color theme
Display Brightness	TFT display brightness level

These settings can be modified during runtime and are automatically written to persistent storage.

13.6 Ethernet Configuration

The Settings Manager stores Ethernet configuration independently from the networking subsystem.

Supported configuration includes:

DHCP mode
Static IP address
Gateway
Subnet mask
Primary DNS server
Secondary DNS server

When static addressing is enabled, these values are automatically supplied to the Ethernet Manager during initialization.

13.7 Wi-Fi Profile Management

The firmware supports persistent storage of multiple Wi-Fi profiles.

Each profile contains:

SSID
Password

The Settings Manager provides operations to:

Save a Wi-Fi profile
Retrieve a saved profile
Remove a saved profile
Count configured profiles

Stored credentials remain available after device reboots.

13.8 User Interface Settings

The configuration subsystem maintains several user interface preferences.

Supported settings include:

Setting	Description
Brightness	TFT display brightness level
Theme	Black theme selection
Language	User interface language

These preferences are loaded automatically during startup and immediately applied to the graphical interface.

13.9 Default Configuration

When the firmware starts for the first time, or when no saved configuration exists, the Settings Manager initializes the following default values:

Setting	Default Value
Hostname	`CRANET`
Display Brightness	255
Language	EN
Theme	Black
Ping Target	192.168.1.1
Ethernet Mode	DHCP Enabled

These defaults ensure that the firmware remains fully operational without requiring manual configuration.

13.10 Configuration Workflow

Power On
     │
     ▼
Open Preferences
     │
     ▼
Load Default Values
     │
     ▼
Read Saved Settings
     │
     ▼
Populate Runtime Configuration
     │
     ▼
Initialize Firmware Modules
     │
     ▼
Runtime Changes
     │
     ▼
Save Updated Configuration

This workflow guarantees that all firmware modules receive consistent configuration data before normal operation begins.

13.11 Integration with Other Components

The Settings Manager provides configuration data to multiple firmware modules.

Component	Configuration Used
`CranetApp`	General system configuration
`EthernetManager`	DHCP and static IP settings
`WiFiManager`	Saved Wi-Fi credentials
`DisplayManager`	Theme and brightness
`ScannerManager`	Default ping target
`ReportManager`	Configuration information for reports

Centralizing configuration management eliminates duplication and ensures consistent behavior across the firmware.

13.12 Design Principles

The Settings and Configuration subsystem is designed around the following principles:

Centralized configuration management
Persistent non-volatile storage
Automatic default initialization
Runtime configuration updates
Modular integration
Consistent configuration access
Simplified maintenance
Scalable architecture for future settings

This architecture provides a reliable and extensible configuration system while keeping individual firmware modules independent of low-level storage operations.

14. Menu Framework

14.1 Overview

The Menu Framework provides the primary navigation system for the Cranet firmware. It organizes all application features into a structured hierarchy of menu pages, allowing users to access networking tools, diagnostics, reports, and configuration through a consistent graphical interface.

Rather than embedding navigation logic within each subsystem, Cranet centralizes all menu management in the MenuController, which coordinates page navigation, item selection, scrolling, and screen transitions.

14.2 Module Information

Files

Menu.cpp
Menu.h

Responsibilities

Menu initialization
Page management
Navigation control
Selection handling
Scroll management
Menu hierarchy
Screen transitions
Action dispatching

14.3 Menu Controller

The MenuController acts as the navigation engine for the firmware.

Its responsibilities include:

Opening menu pages
Moving the current selection
Entering menu items
Returning to previous pages
Returning to the Home screen
Maintaining the current scroll position
Providing the selected menu entry to the display system

The controller separates navigation logic from the graphical rendering layer.

14.4 Menu Hierarchy

The firmware organizes its interface into multiple menu pages.

Home Screen
│
├── Ethernet
├── Wi-Fi
├── Bluetooth
├── Cable Tester
├── IP Scanner
├── Network Tools
├── Reports
├── Settings
└── About

Each menu page contains a collection of entries representing actions, information, or submenus.

14.5 Root Menu

The Root Menu serves as the primary entry point after system startup.

Available sections include:

Menu	Purpose
Home Screen	Main dashboard
Ethernet	Wired network management
Wi-Fi	Wireless networking features
Bluetooth	BLE management
Cable Tester	Cable testing functions
IP Scanner	Network host discovery
Network Tools	Diagnostic utilities
Reports	System reports
Settings	Device configuration
About	Firmware information

The root menu provides centralized access to every major firmware feature.

14.6 Submenu Organization

Each functional subsystem maintains its own dedicated menu page.

Examples include:

Ethernet

IP Address
Gateway
Subnet
DNS
MAC Address
DHCP
Hostname
Link Status
Ping Tools
HTTP / HTTPS Tests

Wi-Fi

Wi-Fi Scan
Hidden Networks
Sorting Options
Saved Networks
Connect Saved Network
Disconnect
Monitor Mode
Network Information

Bluetooth

BLE Scan
Discovered Devices
Device Details
Scan Status

Network Tools

Ping
HTTP GET
HTTPS GET
DNS Lookup
Traceroute

Reports

Generate Report
View Current Report

Settings

Hostname
Display Brightness
Theme
Language
Ethernet Configuration
Wi-Fi Configuration

About

Firmware Information
Hardware Information
Version Details

This hierarchical organization keeps related functionality grouped together, reducing navigation complexity.

14.7 Menu Entries

Every selectable item within the interface is represented by a MenuEntry.

A menu entry contains:

Display title
Associated action
Optional value identifier
Visibility state
Optional child page

Depending on its configuration, selecting a menu entry may:

Open another menu
Execute a firmware action
Display runtime information
Launch a diagnostic tool

14.8 Navigation Operations

The Menu Controller supports several navigation operations.

Operation	Description
Open	Enter a submenu
Enter	Execute the selected menu item
Back	Return to the previous menu
Home	Return to the root menu
Move	Change the selected menu item

These operations are triggered through the Button Navigation System.

14.9 Scroll Management

When a menu contains more entries than can be displayed simultaneously, the Menu Controller automatically manages scrolling.

The controller maintains:

Current selection index
Current scroll position
Visible menu range

This ensures smooth navigation regardless of menu length.

14.10 Menu Workflow

Home Screen
      │
      ▼
Select Menu Item
      │
      ▼
Menu Controller
      │
      ├───────────────┐
      │               │
      ▼               ▼
Open Submenu    Execute Action
      │               │
      ▼               ▼
Update State    Perform Operation
      │               │
      └───────┬───────┘
              ▼
       Refresh Display

This workflow provides a consistent user experience across every feature within the firmware.

14.11 Integration with Other Components

The Menu Framework serves as the primary interface between user input and firmware functionality.

Component	Purpose
`Buttons`	Provides navigation input
`DisplayManager`	Renders menu pages
`CranetApp`	Coordinates menu actions
`EthernetManager`	Supplies Ethernet data
`WiFiManager`	Supplies Wi-Fi information
`BluetoothManager`	Supplies BLE information
`ScannerManager`	Executes scanner actions
`ReportManager`	Generates reports
`SettingsManager`	Provides configuration options

The Menu Framework does not directly implement subsystem functionality. Instead, it acts as the navigation layer that connects the user interface with the underlying firmware modules.

14.12 Design Principles

The Menu Framework is designed around the following principles:

Hierarchical navigation
Modular page organization
Clear separation between navigation and rendering
Action-driven menu entries
Independent page management
Automatic scroll handling
Consistent user interaction
Scalable architecture for future menu expansion

These principles provide a flexible navigation system that remains easy to extend while maintaining a consistent user experience throughout the Cranet firmware.

15. System Utilities

15.1 Overview

The System Utilities module provides a collection of reusable helper functions that support multiple firmware subsystems. Rather than duplicating common operations across the project, Cranet centralizes formatting, data conversion, validation, and vendor identification routines within a dedicated utility library.

These utilities simplify application development while ensuring consistent behavior throughout the firmware.

15.2 Module Information

Files

Utils.cpp
Utils.h

Responsibilities

Data formatting
Network address formatting
Signal strength formatting
Time formatting
Storage formatting
Vendor identification
Wi-Fi security translation
IP address parsing
Menu helper functions
Shared utility operations

15.3 Utility Categories

The utility library is organized into several functional categories.

Category	Purpose
Network Utilities	MAC and IP address formatting
Time Utilities	System uptime formatting
Signal Utilities	RSSI formatting and signal level calculation
Storage Utilities	Byte size formatting
Security Utilities	Wi-Fi security type translation
Vendor Utilities	Hardware vendor identification
Validation Utilities	Input validation and parsing
Interface Utilities	Menu and display helper functions

This organization allows different firmware modules to share common functionality without introducing unnecessary dependencies.

15.4 Network Formatting

The utility library provides helper functions for formatting network-related information into a human-readable format.

Supported operations include:

Function	Description
`formatMac()`	Converts a MAC address into standard hexadecimal notation
`formatIp()`	Converts an IPv4 address into dotted-decimal notation
`parseIp()`	Parses a text string into an IPv4 address object

These functions ensure that networking information is displayed consistently throughout the graphical interface.

15.5 Time Formatting

The firmware includes a helper function for formatting system uptime.

formatUptime() converts the system runtime from milliseconds into a readable representation.

Example formats include:

00:15:42
02:48:11
3d 12:21:54

This formatting is used throughout the firmware wherever runtime duration is displayed.

15.6 Signal Strength Utilities

Wireless signal information is standardized through dedicated helper functions.

Supported operations include:

Function	Description
`formatRssi()`	Formats RSSI values in dBm
`signalBars()`	Converts RSSI values into graphical signal levels

Signal quality is classified into five levels ranging from 0 to 4 bars, providing a simple visual representation for the user interface.

15.7 Storage Formatting

The utility library includes helper functions for displaying storage sizes.

formatBytes() automatically converts byte counts into appropriate units.

Supported units include:

Bytes (B)
Kilobytes (KB)
Megabytes (MB)

This improves readability when displaying storage-related information.

15.8 Wi-Fi Security Translation

Wireless encryption values reported by the ESP32 networking stack are converted into descriptive labels.

Supported security types include:

Security Type	Display Label
Open	Open
WEP	WEP
WPA-PSK	WPA-PSK
WPA2-PSK	WPA2-PSK
WPA/WPA2	WPA/WPA2
WPA2 Enterprise	WPA2-Enterprise
WPA3	WPA3-PSK
Unknown	Unknown

This translation allows scan results to present security information in a user-friendly format.

15.9 Vendor Identification

The utility library maintains an internal Organizationally Unique Identifier (OUI) database for identifying hardware manufacturers.

When provided with a MAC address, the vendorFromMac() function extracts the first three bytes (OUI) and compares them against the internal vendor table.

The current implementation includes vendor mappings for manufacturers such as:

Espressif
Google
Apple
Philips
Samsung
Xiaomi
Huawei
Cisco
Ubiquiti
Netgear
TP-Link
Intel
Texas Instruments

If no matching OUI is found, the vendor is reported as Unknown.

15.10 User Interface Helpers

Several utility functions simplify graphical interface behavior.

Examples include:

Function	Purpose
`yesNo()`	Converts Boolean values into "Yes" or "No"
`portListLabel()`	Formats a list of network ports
`isHiddenSsid()`	Detects hidden Wi-Fi networks
`clampMenuIndex()`	Prevents menu selection from exceeding valid limits

These helpers provide consistent formatting and validation throughout the firmware.

15.11 Integration with Other Components

The utility library is shared across multiple firmware modules.

Component	Utility Usage
`DisplayManager`	Formats information for display
`WiFiManager`	RSSI formatting, security labels, hidden SSID detection
`EthernetManager`	MAC and IP address formatting
`BluetoothManager`	Vendor identification
`ScannerManager`	MAC formatting, vendor lookup, port list formatting
`ReportManager`	Human-readable report values
`MenuController`	Menu index validation

This shared implementation minimizes duplicate code and maintains consistent formatting across the application.

15.12 Design Principles

The System Utilities module is designed around the following principles:

Reusable helper functions
Centralized formatting logic
Consistent user interface presentation
Lightweight implementation
Low module coupling
Shared utility access
Simple maintenance
Scalable architecture for future helper functions

By centralizing common operations into a dedicated utility library, the Cranet firmware remains cleaner, easier to maintain, and more consistent across all subsystems.

16. Project Resources

16.1 Overview

The Cranet project is organized as a self-contained Arduino/ESP32 firmware project. All source code, configuration, hardware definitions, and shared data structures are maintained within a single project directory, making the firmware straightforward to build, maintain, and extend.

The project follows a modular architecture where each subsystem is implemented as an independent component with dedicated header and source files.

16.2 Project Layout

The firmware consists of the following primary resources:

Resource	Purpose
`cranet.ino`	Main firmware entry point
`App.*`	Central application controller
`Display.*`	Graphical display management
`Buttons.*`	Button input handling
`Menu.*`	Menu navigation framework
`WiFiManager.*`	Wi-Fi management subsystem
`BluetoothManager.*`	Bluetooth Low Energy subsystem
`EthernetManager.*`	Ethernet networking subsystem
`Scanner.*`	Network scanner and diagnostics
`ReportManager.*`	Report generation engine
`Settings.*`	Persistent configuration manager
`Utils.*`	Shared utility functions
`CranetConfig.h`	Global firmware configuration
`CranetTypes.h`	Shared data structures and type definitions

16.3 Source Files

Each functional module is implemented using a paired source and header file.

Source File	Header File	Description
`App.cpp`	`App.h`	Main application controller
`Display.cpp`	`Display.h`	Display rendering engine
`Buttons.cpp`	`Buttons.h`	Button processing and navigation
`Menu.cpp`	`Menu.h`	Menu framework
`WiFiManager.cpp`	`WiFiManager.h`	Wi-Fi subsystem
`BluetoothManager.cpp`	`BluetoothManager.h`	Bluetooth subsystem
`EthernetManager.cpp`	`EthernetManager.h`	Ethernet subsystem
`Scanner.cpp`	`Scanner.h`	Scanner and diagnostics
`ReportManager.cpp`	`ReportManager.h`	Report generation
`Settings.cpp`	`Settings.h`	Configuration management
`Utils.cpp`	`Utils.h`	Shared helper utilities

This organization keeps implementation details separate from public interfaces while improving maintainability.

16.4 Configuration Resources

The firmware uses dedicated header files to centralize project-wide definitions.

`CranetConfig.h`

Contains global firmware configuration, including hardware-related constants, feature configuration, default values, and compile-time settings shared across the application.

`CranetTypes.h`

Defines common data structures, enumerations, and shared object types used by multiple firmware modules, ensuring consistency throughout the project.

16.5 Entry Point

The firmware entry point is:

cranet.ino

The Arduino sketch is responsible for:

Initializing the application
Calling the system setup routine
Executing the continuous runtime loop

All major application logic is delegated to the CranetApp class, keeping the sketch file lightweight.

16.6 Project Dependencies

The project is built on the Arduino framework for the ESP32 platform and integrates several hardware and networking libraries.

Major dependency categories include:

ESP32 Arduino Core
Ethernet libraries
Wi-Fi libraries
Bluetooth Low Energy libraries
TFT graphics libraries
Preferences (Non-Volatile Storage)
FreeRTOS synchronization primitives

These libraries provide the hardware abstraction required by the Cranet firmware while allowing application code to remain modular.

16.7 Shared Resources

Several resources are shared across all firmware modules.

These include:

Global configuration values
Common data structures
Runtime status information
Utility helper functions
Menu definitions
Network formatting helpers
Vendor identification data

Centralizing shared resources minimizes code duplication and improves consistency throughout the project.

16.8 Build Organization

The project follows the standard Arduino project structure.

Firmware
     │
     ▼
Arduino Sketch
     │
     ▼
Application Controller
     │
     ▼
Subsystem Managers
     │
     ▼
Hardware Drivers

This layered organization separates application logic from hardware-specific functionality, simplifying future maintenance and feature development.

16.9 Development Characteristics

The project structure emphasizes:

Modular source organization
Separation of interface and implementation
Centralized configuration
Shared reusable utilities
Independent subsystem development
Maintainable code organization

Each subsystem can be modified or extended with minimal impact on the remainder of the firmware.

16.10 Resource Relationships

                cranet.ino
                     │
                     ▼
                 CranetApp
                     │
     ┌───────────────┼───────────────┐
     │               │               │
     ▼               ▼               ▼
Display         Networking       Configuration
     │               │               │
     ├───────┐   ┌───┴────┐      ┌───┴────┐
     ▼       ▼   ▼        ▼      ▼        ▼
Buttons  Menu  Wi-Fi  Ethernet  Settings  Utils
                     │
             ┌───────┼────────┐
             ▼       ▼        ▼
      Bluetooth  Scanner  Reports

This architecture illustrates how individual modules cooperate while remaining logically independent.

16.11 Version Control Resources

The project includes:

Resource	Purpose
`.gitignore`	Excludes generated and temporary files from version control

Maintaining a clean repository helps ensure reproducible builds and simplifies collaboration during development.

16.12 Design Principles

The project resources are organized around the following principles:

Modular source layout
Clear separation of responsibilities
Consistent file organization
Centralized configuration
Shared reusable components
Minimal inter-module dependencies
Maintainable project structure
Scalable architecture for future development

This organization provides a clean and extensible foundation for ongoing development of the Cranet firmware while supporting future hardware capabilities and software enhancements.

17. Build and Deployment

17.1 Overview

The Cranet firmware is developed using the Arduino framework for the ESP32-S3 platform. The project is organized as a standard Arduino sketch, with cranet.ino serving as the application entry point and the remaining functionality implemented through modular C++ source files.

Building the firmware compiles all project modules into a single executable image that can be uploaded to the target hardware.

17.2 Project Entry Point

The firmware build begins from the following sketch:

cranet.ino

During compilation, the Arduino build system automatically includes all project source files referenced by the sketch.

The application startup sequence consists of:

Firmware initialization
Hardware initialization
Application setup
Continuous runtime loop

17.3 Source Compilation

The build process compiles the project's C++ modules, including:

Application controller
Display subsystem
Button handler
Menu framework
Ethernet manager
Wi-Fi manager
Bluetooth manager
Scanner manager
Report manager
Settings manager
Utility library

Each module is compiled independently before being linked into the final firmware image.

17.4 Build Dependencies

Successful compilation requires the Arduino framework together with the libraries referenced by the project source code.

These include libraries for:

ESP32 system support
Ethernet networking
Wi-Fi networking
Bluetooth Low Energy
TFT display control
Non-volatile preferences storage
FreeRTOS synchronization

These dependencies provide the hardware abstraction layer used throughout the firmware.

17.5 Build Workflow

Source Files
      │
      ▼
Arduino Build System
      │
      ▼
Compile Individual Modules
      │
      ▼
Link Firmware
      │
      ▼
Generate ESP32 Firmware Image
      │
      ▼
Upload to ESP32-S3

This workflow converts the project source code into an executable firmware image suitable for deployment on the target device.

17.6 Deployment Process

Deployment consists of transferring the compiled firmware image to the ESP32-S3 over a supported programming interface.

A typical deployment sequence is:

Connect the ESP32-S3 development board.
Select the appropriate board configuration.
Select the correct serial port.
Build the firmware.
Upload the compiled image.
Reset the device.
Verify successful startup.

Following deployment, the firmware initializes all configured subsystems during boot.

17.7 Startup Sequence

After flashing, the firmware follows a structured initialization sequence.

Power On
     │
     ▼
ESP32 Bootloader
     │
     ▼
Firmware Startup
     │
     ▼
Initialize Hardware
     │
     ▼
Load Configuration
     │
     ▼
Initialize Managers
     │
     ▼
Launch User Interface
     │
     ▼
Enter Runtime Loop

This sequence ensures that configuration, networking, and the graphical interface are initialized before normal operation begins.

17.8 Runtime Initialization

During startup, the firmware initializes major application components in an organized manner.

Typical initialization includes:

Display subsystem
Button interface
Settings manager
Ethernet manager
Wi-Fi manager
Bluetooth manager
Scanner manager
Report manager
Menu framework

Once initialization completes, the application enters its continuous runtime loop.

17.9 Project Organization

The firmware follows the standard Arduino project layout.

cranet.ino
        │
        ▼
Application Controller
        │
        ▼
Subsystem Managers
        │
        ▼
Hardware Interfaces

This organization keeps the sketch lightweight while placing application logic inside dedicated C++ modules.

17.10 Deployment Characteristics

The deployment architecture provides:

Single firmware image
Modular source compilation
Centralized application startup
Automatic subsystem initialization
Integrated hardware support
Consistent runtime initialization

This approach simplifies firmware deployment while maintaining a modular internal architecture.

17.11 Build Considerations

When building the firmware, ensure that:

The target board matches the ESP32-S3 hardware.
Required libraries are installed in the Arduino environment.
All project source files remain within the same project directory.
The firmware is compiled before attempting deployment.

These considerations help ensure a successful build and upload process.

17.12 Design Principles

The build and deployment process follows several architectural principles:

Standard Arduino project structure
Modular compilation
Single application entry point
Centralized startup sequence
Automatic subsystem initialization
Hardware abstraction through libraries
Maintainable deployment workflow
Scalable firmware architecture

These principles provide a predictable and maintainable workflow for building, deploying, and running the Cranet firmware on supported ESP32-S3 hardware.

18. Troubleshooting

18.1 Overview

This section provides guidance for diagnosing and resolving common issues that may occur while building, deploying, or operating the Cranet firmware. Since the firmware is composed of multiple independent subsystems, troubleshooting should begin by identifying the affected module before investigating its specific configuration or runtime state.

The modular architecture allows most issues to be isolated to a single subsystem without affecting the remainder of the application.

18.2 Firmware Does Not Start

Possible Causes

Firmware upload was unsuccessful.
Incorrect ESP32-S3 board configuration.
Hardware initialization failure.
Missing or incompatible project dependencies.

Recommended Checks

Verify that the firmware was uploaded successfully.
Confirm the correct ESP32-S3 board is selected.
Perform a device reset.
Rebuild the firmware to ensure compilation completed without errors.

18.3 Display Issues

Symptoms

Blank display
Display not refreshing
Incorrect screen rendering

Recommended Checks

Verify the TFT display is connected correctly.
Confirm the display initializes during startup.
Verify the configured display driver matches the hardware.
Restart the device after any hardware changes.

18.4 Ethernet Connectivity Issues

Symptoms

No IP address assigned
Network cable detected but no connectivity
Unable to reach network hosts

Recommended Checks

Verify the Ethernet cable connection.
Confirm the network switch or router is operational.
Check whether DHCP or Static IP mode is configured correctly.
Verify gateway, subnet mask, and DNS settings when using static addressing.
Confirm the Ethernet interface reports an active link.

18.5 Wi-Fi Issues

Symptoms

No wireless networks detected
Unable to connect to a saved network
Unexpected connection failures

Recommended Checks

Verify nearby Wi-Fi networks are available.
Confirm stored SSID and password are correct.
Ensure the target network is within signal range.
Retry a new network scan.
Remove and recreate saved Wi-Fi profiles if necessary.

18.6 Bluetooth Issues

Symptoms

No BLE devices discovered
Scan results remain empty
Bluetooth scan does not begin

Recommended Checks

Verify nearby Bluetooth Low Energy devices are advertising.
Confirm Bluetooth scanning has been started.
Wait for the scan cycle to complete before viewing results.
Retry the scan if no devices are detected.

18.7 Scanner and Diagnostic Issues

Symptoms

No hosts discovered
Ping failures
Port scan returns no results
Diagnostic tools fail to complete

Recommended Checks

Verify the device is connected to an active network.
Confirm the target host is reachable.
Ensure the selected IP address belongs to the active subnet.
Retry the diagnostic operation after verifying network connectivity.

18.8 Configuration Issues

Symptoms

Settings are not retained after reboot
Default values reappear
Saved Wi-Fi profiles disappear

Recommended Checks

Verify that configuration changes have been saved.
Restart the firmware after updating settings.
Confirm non-volatile storage initializes successfully during startup.
Reconfigure the affected settings if persistent storage has been cleared.

18.9 Report Generation Issues

Symptoms

Report contains incomplete information
Missing subsystem data
Empty report entries

Recommended Checks

Ensure all required subsystem managers have been initialized.
Verify the relevant subsystem has completed its operation before generating a report.
Generate a new report after performing the desired diagnostic or scan.

18.10 Build Issues

Symptoms

Compilation errors
Missing library errors
Upload failures

Recommended Checks

Confirm all required libraries are installed.
Verify the ESP32 board package is available.
Ensure all project source files remain within the project directory.
Rebuild the firmware after resolving compilation errors.

18.11 General Diagnostic Workflow

Identify Problem
        │
        ▼
Determine Affected Subsystem
        │
        ▼
Verify Hardware
        │
        ▼
Verify Configuration
        │
        ▼
Retry Operation
        │
        ▼
Generate Diagnostic Report
        │
        ▼
Review Runtime Status

Following a structured diagnostic process helps isolate issues efficiently while minimizing unnecessary configuration changes.

18.12 Troubleshooting Principles

The Cranet firmware is designed to simplify troubleshooting through:

Modular subsystem isolation
Centralized configuration management
Runtime status reporting
Built-in diagnostic utilities
Structured report generation
Consistent initialization sequence
Reusable utility functions
Independent subsystem operation

These design principles make it easier to identify, isolate, and resolve issues while maintaining reliable operation across the firmware.

19. License

19.1 Copyright

This project, including its source code, documentation, architecture, user interface, graphics, and associated assets, was independently designed and developed by HASHIM.

19.2 Ownership

Cranet is an original software project created by HASHIM and is intended to demonstrate embedded systems engineering, network programming, firmware architecture, and software development capabilities.

Unless explicitly stated otherwise, all intellectual property rights relating to this project remain the exclusive property of the author.

19.3 Usage

This repository is provided for portfolio, educational, and demonstration purposes only.

Without prior written permission from the author, you may not:

Copy or redistribute the source code.
Modify or create derivative works.
Use any portion of the project in commercial products.
Reproduce the documentation or project assets.
Claim this project or any part of it as your own work.

19.4 Third-Party Components

This project utilizes third-party libraries and development frameworks that remain the property of their respective authors and are distributed under their own licenses.

Examples include libraries provided by the Arduino and ESP32 ecosystems.

Ownership of the Cranet application itself remains with the project author.

19.5 Contact

For licensing inquiries, collaboration opportunities, or permission requests, please contact:

HASHIM

LinkedIn: https://linkedin.com/in/ashhim

GitHub: https://github.com/ashhim

19.6 Disclaimer

This software is provided "as is" without any express or implied warranty.

The author shall not be held liable for any direct, indirect, incidental, or consequential damages arising from the use or inability to use this software.

Users assume full responsibility for any deployment or use of the project.

19.7 Summary

Project: Cranet
Author: HASHIM
Year: 2026
Status: Original proprietary software

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.gitignore		.gitignore
App.cpp		App.cpp
App.h		App.h
BluetoothManager.cpp		BluetoothManager.cpp
BluetoothManager.h		BluetoothManager.h
Buttons.cpp		Buttons.cpp
Buttons.h		Buttons.h
CranetConfig.h		CranetConfig.h
CranetTypes.h		CranetTypes.h
Display.cpp		Display.cpp
Display.h		Display.h
EthernetManager.cpp		EthernetManager.cpp
EthernetManager.h		EthernetManager.h
Menu.cpp		Menu.cpp
Menu.h		Menu.h
README.md		README.md
ReportManager.cpp		ReportManager.cpp
ReportManager.h		ReportManager.h
Scanner.cpp		Scanner.cpp
Scanner.h		Scanner.h
Settings.cpp		Settings.cpp
Settings.h		Settings.h
Utils.cpp		Utils.cpp
Utils.h		Utils.h
WiFiManager.cpp		WiFiManager.cpp
WiFiManager.h		WiFiManager.h
cranet.ino		cranet.ino

Folders and files

Latest commit

History

Repository files navigation

Contents

1. System Overview

1.1 Introduction

1.2 Purpose

1.3 Key Features

1.4 System Architecture Overview

1.5 Startup Sequence

1.6 Design Principles

2. Hardware Architecture

2.1 Hardware Overview

2.2 Core Hardware Components

2.3 System Hardware Block Diagram

2.4 Display System

2.5 Ethernet Interface

2.6 Wireless Interfaces

Wi-Fi

Bluetooth Low Energy (BLE)

2.7 User Input System

2.8 GPIO Configuration

Display Interface

Ethernet Interface

Navigation Buttons

2.9 Hardware Design Philosophy

3. Firmware Architecture

3.1 Architecture Overview

3.2 Firmware Structure

3.3 Application Controller

3.4 Firmware Initialization Sequence

3.5 Runtime Execution Model

3.6 Module Interaction

3.7 Object-Oriented Design

3.8 State Management

3.9 Design Principles

4. Project Directory Structure

4.1 Directory Overview

4.2 Project Structure

4.3 Entry Point

4.4 Core Application Layer

4.5 Hardware Abstraction Layer

4.6 Service Layer

4.7 Configuration Files

4.8 Modular Design Philosophy

5. Core System Components

5.1 Component Overview

5.2 Application Controller

Responsibilities

5.3 Display Manager

Responsibilities

5.4 Menu Controller

Responsibilities

5.5 Button Controller

Responsibilities

5.6 Ethernet Manager

Responsibilities

5.7 Wi-Fi Manager

Responsibilities

5.8 Bluetooth Manager

Responsibilities

5.9 Scanner Manager

Responsibilities

5.10 Report Manager

Responsibilities

5.11 Settings Manager

Responsibilities

5.12 Utility Library

Responsibilities

5.13 Shared Configuration

5.14 Component Relationships

6. Display User Interface

6.1 User Interface Overview

6.2 Display Hardware

6.3 Display Manager

Responsibilities

6.4 Boot Screen

6.5 Screen Layout

6.6 Header Section