Interface and Application Programming

01 · Overview

For Assignment 13, I developed the SmartPi Admin Web App, a comprehensive browser-based interface for configuring, monitoring, and managing the SmartPi Assistant device. The application provides an intuitive Material Design 3 interface that allows users to configure all device settings, manage message inputs, control audio output, configure network connections, and perform system testing — all from a laptop or mobile device.

The SmartPi Admin Web App serves as the central control panel for the SmartPi ecosystem, bridging the gap between the cloud-based N8N workflow, the local MCP bridge server, and the embedded SmartPi device running CircuitPython firmware.

02 · Application Architecture

System Integration

The SmartPi Admin Web App integrates with the broader SmartPi ecosystem:

• SmartPi Device (Pico W): Direct HTTP communication on local network for configuration and status
• MCP Bridge Server: Configuration for bridge server IP and port settings
• N8N Workflow: Message input configuration (Email, Calendar, Weather, Slack)
• Local Storage: Browser localStorage for UI preferences and device discovery
• File System: JSON-based configuration profiles and message logs (planned)

Technology Stack

The application is built using modern web technologies optimized for performance, maintainability, and user experience:

Component	Technology	Purpose
Framework	React 18 + TypeScript	Component-based UI with type safety
UI Library	Material-UI v6 (MUI)	Material Design 3 components and theming
Build Tool	Vite	Fast development and optimized production builds
State Management	Zustand	Lightweight state management for device config
HTTP Client	Axios	API communication with retry logic
File System	File System Access API	Local JSON file read/write for configs

03 · Design Principles

Material Design 3

The application follows Material Design 3 (Material You) principles, Google's latest design system. Key design elements include:

• Dynamic Color System: Custom theme with SmartPi brand color (International Orange #FF3300) as primary
• Dark Mode Default: Optimized for OLED displays and low-light environments
• Elevation & Shadows: Material elevation levels for visual hierarchy
• Motion Design: Smooth transitions (200-300ms) for state changes
• Typography Scale: Material Design 3 type scale for consistent text hierarchy
• Rounded Corners: 12px border radius for modern, friendly appearance

Responsive Design

The interface adapts seamlessly across device sizes using Material Design breakpoints:

• Mobile (xs, sm): Bottom navigation, single-column layout, simplified controls
• Tablet (md): Mini drawer sidebar, two-column grids, horizontal tabs
• Desktop (lg, xl): Permanent sidebar, multi-column layouts, full feature set

Accessibility

Built-in accessibility features from Material-UI ensure WCAG 2.1 Level AA compliance:

• Keyboard navigation support
• Screen reader compatibility (ARIA labels)
• High contrast mode support
• Minimum 48px touch targets (exceeds 44px standard)
• Focus indicators with Material ripple effects

04 · Application Interface

Top Navigation Bar

The top navigation bar provides global controls and device status:

• App Title: "SmartPi Admin App" branding
• Device Selector: Dropdown to switch between multiple SmartPi devices (desktop only)
• Status Indicator: Visual badge showing online/offline status
• Debug Mode Toggle: Enable/disable debug mode with serial terminal
• Theme Toggle: Switch between dark and light modes

Top Navigation Bar: App title, device selector, status indicator, debug mode toggle, and theme toggle

Serial Console Terminal

When Debug Mode is enabled, a serial console terminal appears at the bottom of the window, displaying real-time debug messages from the SmartPi device. This provides detailed logging for troubleshooting and development.

Serial Console Terminal: Debug mode terminal window at bottom with real-time debug messages, close button, and timestamped logs

05 · Settings Tabs

The Settings page is organized into five main tabs, each focusing on a specific aspect of device configuration:

Tab 1: Display Settings

The Display tab configures the 64x64 LED matrix display parameters:

Display Hardware Configuration

• Bit Depth: Dropdown (1-6 bit) for color depth selection
• Display Width: Number input (1-64 pixels) matching physical display
• Display Height: Number input (1-64 pixels) matching physical display
• Rotation: Dropdown (0°, 90°, 180°, 270°) for display orientation
• Serpentine Mode: Toggle switch for pixel mapping mode

Text Rendering Configuration

• Line Scale: Dropdown (1x, 2x, 3x) for text size multiplier
• Maximum Lines: Dropdown (1-8 lines) for messages per screen
• Line Spacing: Number input (-5 to +5) for line spacing adjustment
• Text Alignment: Dropdown (Left, Center, Right)

Positioning & Theme Stripe

• Vertical/Horizontal Offset: Number inputs for text positioning
• Left/Right Margins: Number inputs for edge spacing
• Theme Stripe: Toggle and width control for colored edge indicator

Display Settings Tab: Display hardware configuration (bit depth, width, height, rotation), text rendering settings (line scale, maximum lines, alignment), positioning controls, and theme stripe configuration

Tab 2: Messages Settings

The Messages tab configures input sources and message display behavior:

Input Source Configuration

Each input source (Email, Calendar, Weather, Slack) has its own configuration card with:

• Enable/Disable Toggle: Master switch for each input source
• Alert Sound Dropdown: Select from available alert sounds (Email, Calendar, Weather, Slack, or No Sound)
• Test Button: Play selected alert sound for testing
• Update Frequency Dropdown: Schedule updates (15 min, 30 min, 1 hr, 2 hrs, 6 hrs, 24 hrs)

Message Display Configuration

• Message Priority Filter: Dropdown (Urgent, Important, Normal) to filter displayed messages
• Display Time: Dropdown (1-30 seconds) for how long each message is shown

Messages Settings Tab: Input source configuration cards (Email, Calendar, Weather, Slack) with enable/disable toggles, alert sound dropdowns with test buttons, update frequency selectors, message priority filter, and display time settings

Tab 3: Audio Settings

The Audio tab controls audio output behavior:

• Enable Speech Alerts: Toggle to enable text-to-speech for messages
• Enable Sound Alerts: Toggle to enable audio alert sounds
• Mutual Exclusivity: When one is enabled, the other automatically disables

Audio Settings Tab: Enable Speech Alerts and Enable Sound Alerts toggle switches with descriptions explaining their mutual exclusivity

Tab 4: Network Settings

The Network tab configures WiFi and device connections:

WiFi Configuration

• WiFi Name (SSID): Text input for network name
• WiFi Password: Password input (masked) for network authentication

Device Connection

• SmartPi Device IP Address: Text input for device IP on local network
• SmartPi Device Port: Number input (1024-65535) for HTTP server port

MCP Bridge Server

• MCP Bridge IP Address: Text input for bridge server IP or hostname
• MCP Bridge Port: Number input (1024-65535) for bridge server port

Network Settings Tab: Three sections (WiFi Configuration, Device Connection, MCP Bridge Server) with input fields for SSID, password, IP addresses, and ports

Tab 5: Advanced Settings

The Advanced tab contains system-level configurations:

• Enable DEBUG_FLAG: Toggle to enable debug messages in serial terminal when Debug Mode is on
• CPU Frequency: Dropdown (125 MHz, 187.5 MHz, 250 MHz) for processor clock speed

Advanced Settings Tab: Enable DEBUG_FLAG toggle switch with description, CPU frequency dropdown (125 MHz, 187.5 MHz, 250 MHz), and info alert about restart requirement

06 · Key Design Features

Form Validation & User Feedback

• Real-time Validation: Input validation with immediate feedback
• Helper Text: Contextual help text below each form field
• Unsaved Changes Alert: Visual indicator when settings have been modified
• Save/Reset Actions: Clear action buttons with Material Design styling

Input Source Cards

Each input source (Email, Calendar, Weather, Slack) is presented as a card with:

• Color-coded Icons: Unique color scheme per input type for visual distinction
• Enable/Disable Toggle: Prominent switch at the top of each card
• Collapsible Configuration: Settings hidden when input is disabled
• Test Functionality: Test button next to alert sound dropdown for immediate feedback

Responsive Behavior

The interface adapts to screen size:

• Mobile: Bottom navigation replaces sidebar, single-column forms, simplified controls
• Tablet: Mini drawer (icons only), two-column grids, horizontal scrolling tabs
• Desktop: Full sidebar navigation, multi-column layouts, all features visible

07 · User Experience Enhancements

State Management

• Unsaved Changes Tracking: Visual indicator when settings differ from saved state
• Form State Persistence: Settings preserved during tab navigation
• Device Status Polling: Automatic status updates every 5 seconds

Error Handling

• Connection Timeout: 5-second timeout with retry logic
• User-friendly Error Messages: Material Snackbar alerts for errors
• Network Error Detection: Distinguishes device errors from network issues
• Recovery Suggestions: Actionable error messages with next steps

Accessibility Features

• Keyboard Navigation: Full keyboard support for all controls
• Screen Reader Support: ARIA labels and semantic HTML
• Focus Management: Clear focus indicators with Material ripple
• High Contrast Mode: Supports system high contrast settings

08 · Implementation Details

Component Architecture

The application follows a modular component structure:

• Layout Components: AppHeader, AppDrawer, BottomNav, MainLayout
• Settings Components: SettingsPage with tabbed interface
• Shared Components: DeviceSelector, StatusIndicator, ConfirmDialog
• Utility Libraries: API client, storage manager, form validators

API Communication

Direct HTTP/REST communication with SmartPi device:

• Base URL: Configurable device IP and port
• Endpoints: /status, /config, /power, /device/restart, /wifi/*, etc.
• Request/Response: JSON format with error handling
• Retry Logic: Exponential backoff for failed requests

Local Storage Strategy

Current implementation uses browser localStorage for:

• Device discovery and selection
• UI preferences (theme mode, auto-refresh)
• Test history (last 50 results)
• Configuration backups

09 · Testing & Validation

Development Testing

• Standalone HTML Demo: Created settings-demo.html for UI/UX review without build process
• Component Isolation: Each component tested independently
• Responsive Testing: Verified across mobile, tablet, and desktop breakpoints
• Browser Compatibility: Tested on Chrome, Firefox, Safari, Edge

User Testing

• Intuitive Navigation: Tab-based organization reduces cognitive load
• Clear Visual Hierarchy: Material Design elevation and spacing guide attention
• Immediate Feedback: Test buttons, status indicators, and validation messages
• Error Recovery: Clear error messages with actionable next steps

10 · Future Enhancements

Planned features for future iterations:

• Prompt Editor: UI for editing and testing LLM prompts used in N8N workflow
• Message History: View and search through processed messages for debugging
• Configuration Profiles: Save/load named configuration profiles
• Firmware Management: Upload and flash .uf2 firmware files via File System Access API
• System Testing: Comprehensive test suite for device connectivity and message flow
• Analytics Dashboard: Visualize message statistics and device usage

11 · Conclusion

The SmartPi Admin Web App provides a comprehensive, user-friendly interface for managing the SmartPi Assistant device. Built with Material Design 3 principles, the application offers:

• ✅ Intuitive Configuration: Tab-based organization with clear visual hierarchy
• ✅ Responsive Design: Seamless experience across mobile, tablet, and desktop
• ✅ Accessibility: WCAG 2.1 Level AA compliant with keyboard and screen reader support
• ✅ Modern Architecture: React + TypeScript + Material-UI for maintainability and extensibility
• ✅ User Experience: Real-time feedback, error handling, and state management

The application successfully bridges the gap between cloud services, local infrastructure, and embedded devices, providing a single interface for complete SmartPi ecosystem management. System integration details with N8N workflow and MCP bridge server will be documented upon completion of the integration implementation.