Trailside Kiosk: Project Structure Initialization Guide

Embarking on a new software project can be both exciting and daunting. Establishing a solid foundation is key to ensuring long-term success and maintainability. In this article, we'll walk through the process of initializing the project structure for Trailside Kiosk, an ESP32-based offline educational trail guide kiosk. This guide will cover everything from hardware targets and architectural considerations to content structure and repository organization.

Understanding the Project Vision and Scope

Before diving into the technical details, it's essential to grasp the project's vision and scope. Trailside Kiosk aims to provide an accessible and engaging educational resource for visitors of natural trails. By leveraging an ESP32 microcontroller and a compact display, the kiosk will offer information about local fauna, flora, fungi, geology, and cultural aspects of the area. The content philosophy emphasizes education over enforcement, fostering a sense of curiosity and stewardship among users. The initial scope of v1 focuses on the high desert region, specifically around Roosevelt Lake, Arizona. Our mascot for this project is the majestic Bald Eagle, symbolizing the natural beauty and conservation efforts in the region.

Key Objectives of the Trailside Kiosk Project

1. Offline Accessibility: The kiosk operates offline, ensuring availability in remote areas without internet connectivity.
2. Educational Content: Providing comprehensive information on local flora, fauna, fungi, geology, and cultural heritage.
3. User-Friendly Interface: Designing an intuitive and engaging user experience.
4. Low Power Consumption: Optimizing for battery-powered operation.
5. Scalability and Maintainability: Creating a project structure that can evolve and adapt to future requirements.

Hardware Targets: Choosing the Right Components

Selecting the appropriate hardware is a crucial first step. For Trailside Kiosk, we've identified the following key hardware components:

• ESP32-WROOM: This is our primary development board due to its powerful processing capabilities, integrated Wi-Fi and Bluetooth, and ample memory. The ESP32's dual-core processor and generous RAM are well-suited for running the kiosk's software and handling user interactions.
• ST7735S Display (80x160): This compact display provides a clear and vibrant interface for displaying information. Its small size and low power consumption make it ideal for a kiosk application.
• Bluetooth HID Keyboard Input: Bluetooth connectivity allows users to interact with the kiosk using a wireless keyboard, providing a familiar and efficient input method.
• Internal Flash Storage (~4MB): The ESP32's internal flash storage provides sufficient space for storing the kiosk's firmware, content, and configuration files.

Why These Components?

• ESP32-WROOM: Offers a balance of performance, features, and cost-effectiveness. Its Wi-Fi capabilities are essential for the captive portal functionality, while Bluetooth enables keyboard input.
• ST7735S Display: Provides a compact and energy-efficient display solution. Its 80x160 resolution is sufficient for displaying text and simple graphics.
• Bluetooth HID Keyboard: Allows for a user-friendly input method, especially for longer text entries or navigation.
• Internal Flash Storage: Eliminates the need for external storage devices, simplifying the hardware setup and reducing power consumption.

Architectural Overview: Designing the Software Framework

The software architecture of Trailside Kiosk is designed to be modular and scalable. It comprises three main components:

• Captive Portal: This component creates a local Wi-Fi network (AP mode) and redirects users to a web-based interface. It handles DNS and HTTP requests, serving the kiosk's web application from the ESP32's flash storage.
• Single Page Application (SPA): The user interface is built as a single-page application using HTML, JavaScript, and CSS. This approach provides a responsive and interactive user experience.
• Usage Stats: This module tracks user interactions and collects anonymous usage data. This information can be used to improve the kiosk's content and functionality.

Captive Portal

The captive portal is a critical component for providing a seamless user experience. When a user connects to the kiosk's Wi-Fi network, they are automatically redirected to the kiosk's web interface. This is achieved by:

1. AP Mode: The ESP32 acts as a Wi-Fi access point, creating a local network.
2. DNS Server: The ESP32 runs a DNS server that intercepts all domain name requests.
3. HTTP Server: A lightweight HTTP server serves the kiosk's web application files.

When a user tries to access any website, the DNS server redirects the request to the ESP32's HTTP server, which serves the kiosk's index.html file. This ensures that users are always presented with the kiosk's interface, even if they try to browse other websites.

Single Page Application (SPA)

The user interface is built as a single-page application (SPA) to provide a smooth and responsive experience. The SPA consists of:

• index.html: The main HTML file that loads the application.
• app.js: The JavaScript code that handles user interactions and updates the UI.
• style.css: The CSS file that defines the kiosk's visual appearance.

The SPA architecture allows for dynamic content updates without requiring full page reloads, resulting in a faster and more fluid user experience. The application logic is implemented in JavaScript, which interacts with the ESP32's file system to retrieve content and manage usage statistics.

Usage Statistics

Collecting usage statistics is essential for understanding how users interact with the kiosk. This data can be used to identify popular content, optimize the user interface, and improve the overall kiosk experience. The usage stats module tracks:

• Page views
• Time spent on each page
• User interactions (e.g., button clicks, search queries)

This data is stored locally on the ESP32 and can be accessed for analysis and reporting. It's crucial to ensure that the data collection is anonymous and respects user privacy.

Content Structure: Organizing Educational Resources

The content structure is designed to be both comprehensive and easily navigable. It covers a wide range of topics related to the natural environment, including:

• Fauna: Birds, mammals, reptiles, insects, fish
• Flora: Trees, cacti, parasitic plants, grasses, flowers
• Fungi: Lichens, mushrooms, molds, symbiotic fungi
• Maps: Trail maps, points of interest
• Safety: Wildlife coexistence, emergency procedures
• Stewardship: Leave No Trace principles, conservation efforts
• Water: Information about local water sources
• Geology: Geological formations, rock types
• Cultural: Historical and cultural significance of the area

Content Categories

Each category is further divided into subcategories to provide a more granular organization. For example, the Fauna category includes subcategories for birds, mammals, reptiles, insects, and fish. This hierarchical structure makes it easy for users to find the information they are looking for.

The content is stored in JSON format, which is a lightweight and flexible data format. Each content item includes the following fields:

• id: A unique identifier for the item
• name: The common name of the species or topic
• scientific_name: The scientific name (if applicable)
• category: The category and subcategory of the item
• summary: A brief overview of the item
• description: A more detailed description
• safety: Safety information (if applicable)
• fun_fact: An interesting fact about the item

Content Example

{
  "id": "bald-eagle",
  "name": "Bald Eagle",
  "scientific_name": "Haliaeetus leucocephalus",
  "category": "fauna/birds",
  "summary": "National bird of the United States. A mating pair resides at Roosevelt Lake.",
  "description": "Once endangered due to DDT pesticide use, bald eagles have made a remarkable recovery.",
  "safety": "Observe from distance. Do not approach nests.",
  "fun_fact": "Bald eagles can see fish from a mile away."
}

This JSON structure allows for easy parsing and display of content within the kiosk application.

Repository Structure: Organizing the Project Files

The repository structure is designed to be logical and easy to navigate. It includes the following directories and files:

trailside-kiosk/
├── README.md
├── LICENSE (MIT)
├── main.py
├── config.json
├── stats.json
├── lib/
│   ├── __init__.py
│   ├── captive_portal.py
│   ├── bt_keyboard.py
│   ├── st7735.py
│   └── menu.py
└── www/
    ├── index.html
    ├── app.js
    ├── style.css
    └── tours/
        ├── content/
        │   ├── fauna/
        │   │   ├── birds/bald-eagle.json
        │   │   ├── mammals/.gitkeep
        │   │   ├── reptiles/rattlesnake.json
        │   │   ├── insects/scorpion.json
        │   │   └── fish/. gitkeep
        │   ├── flora/
        │   │   ├── trees/mesquite.json
        │   │   ├── cacti/saguaro.json
        │   │   ├── parasitic/desert-mistletoe.json
        │   │   ├── grasses-reeds/.gitkeep
        │   │   └── flowers/.gitkeep
        │   ├── fungi/
        │   │   ├── lichens/rock-lichen.json
        │   │   ├── mushrooms/.gitkeep
        │   │   ├── molds/.gitkeep
        │   │   └── symbiotic/mycorrhizae.json
        │   ├── geology/.gitkeep
        │   ├── water/roosevelt-lake. json
        │   ├── cultural/apache-heritage.json
        │   ├── safety/wildlife-coexistence. json
        │   └── stewardship/leave-no-trace.json
        └── maps/.gitkeep

Key Directories and Files

• README.md: This file provides an overview of the project, including its vision, scope, hardware, and architecture.
• LICENSE: The project is licensed under the MIT License, which allows for free use and modification.
• main.py: The main Python script that runs on the ESP32. It initializes the hardware, starts the captive portal, and handles user interactions.
• config.json: This file stores configuration settings for the kiosk, such as Wi-Fi credentials and display settings.
• stats.json: This file stores usage statistics collected by the kiosk.
• lib/: This directory contains Python modules that implement the kiosk's core functionality, such as the captive portal, Bluetooth keyboard input, and display driver.
• www/: This directory contains the kiosk's web application files, including HTML, JavaScript, CSS, and content.
• tours/content/: This directory stores the kiosk's content in JSON format. The content is organized into categories and subcategories, as described in the Content Structure section.

Importance of a Well-Organized Repository

A well-organized repository is crucial for collaboration and maintainability. It makes it easier for developers to understand the project's structure, find files, and contribute code. The Trailside Kiosk repository structure is designed to be intuitive and consistent, ensuring that the project can evolve and adapt to future requirements.

Crafting the README: A Project's First Impression

The README.md file serves as the project's primary documentation and first point of contact for anyone interested in the project. It should provide a clear and concise overview of the project, including its vision, scope, hardware, architecture, and contribution guidelines. For Trailside Kiosk, the README.md will include the following sections:

• Project Vision and Background: A brief explanation of the project's goals and motivations. This section will highlight the educational mission of the kiosk and its focus on promoting environmental stewardship.
• Hardware and Architecture Overview: A summary of the hardware components and software architecture used in the project. This section will provide a high-level understanding of how the kiosk works.
• Content Philosophy (education > enforcement): A discussion of the project's content philosophy, emphasizing education over enforcement. This section will explain how the kiosk aims to engage users and foster a sense of curiosity about the natural environment.
• v1 Scope: High desert / Roosevelt Lake, AZ: A definition of the initial scope of the project, focusing on the high desert region around Roosevelt Lake, Arizona. This section will help set expectations for the content and functionality of the first version of the kiosk.
• Mascot: Bald Eagle: An introduction to the project's mascot, the Bald Eagle. This section will explain the symbolism of the Bald Eagle and its connection to the project's goals.
• Contribution Guidelines (experience-based): Guidelines for contributing to the project, emphasizing experience-based contributions. This section will encourage users to share their knowledge and experiences to improve the kiosk's content and functionality.
• Evolution Roadmap to pocket-ranger: A roadmap for the project's evolution, outlining the long-term vision of turning the kiosk into a pocket-ranger application. This section will provide a glimpse into the future of the project and its potential for expansion.
• MIT License: A statement of the project's licensing terms, indicating that it is licensed under the MIT License.

The Importance of a Detailed README

A comprehensive README.md is essential for attracting contributors, promoting the project, and ensuring its long-term success. It serves as a central source of information for anyone interested in the project, providing a clear understanding of its goals, scope, and how to get involved.

Conclusion: Setting the Stage for Success

Initializing a project's structure is a critical step in the software development lifecycle. By carefully considering hardware targets, architectural design, content organization, and repository structure, we can lay a solid foundation for the Trailside Kiosk project. This comprehensive guide has provided a detailed overview of the key aspects of initializing the project, from understanding the project vision to crafting a detailed README.md. By following these guidelines, we can ensure that Trailside Kiosk is well-positioned for success, providing an engaging and educational resource for visitors of natural trails.

For more information on best practices for open source projects, you can visit the Open Source Guides website. This resource offers valuable insights and guidance on various aspects of open source development, collaboration, and community building.