ACOUSPHONIUM

Quick Start

📣 client selection now propagates easily to "modules" 🦢⚰️🎵 check out the Adding Stuff Guide. it is there for you and you alone

Prerequisites

Before running the startup script, ensure the following (the script will try to do some varification, but it ain't perfect):

1. Ruby:

   1. Run ruby -v and confirm it matches the version in .tool-versions.
   2. If not, make sure you've got the dependencies installed, and we suggest you use asdf, rbenv, or similar tools to manage Ruby versions.
   3. Then, Install Bundler if missing:

   	gem install bundle

   4. Install gems by running:

   bundle install

   5. Ensure mkcert is installed and trusted. While the script tries its best to set things up, it’s recommended to manually run:

      # On Raspberry Pi, if using arm64, you may need to use the following to install mkcert:
      sudo apt-get install libnss3-tools mkcert # official docs reccoemd installing through brew or binaries, but this works
      # Then, run:
      mkcert -install

Running the Server

Use the bin/start script to configure and launch the server.

🟠 Simplest: Just run bin/start -a your_ip for admin access.

Basic Usage

It should be exectutable by default, but if not, run:

chmod +x bin/start

Then, run the script with the desired options. Note that the only required options are -a for admin IPs.

Some important options:

• -a - stand for admin IPs, and is required for access control. Takes a comma-separated list of IPs.
• -r - reset SSL certificates.
• -l - log level. Options are debug, info, warn, error, and fatal. This is optional, and defaults to info. Effects the server and backend logs.
• --http - Run in HTTP-only mode (no HTTPS). This is optional, and defaults to HTTPS.
• -d - set -x for the startup script. Will not be very useful for most users.

Full list of options::

bin/start [options]

Options
	*	-p PORT — Specify HTTP port (default: 1337).
	*	-s PORT — Specify HTTPS port (default: 443).
	*	-l LEVEL — Set log level (default: info).
	*	-a IPS — Comma-separated list of admin IPs for access control.
	*	-d — Enable debug mode (verbose output).
	*	-r — Reset and regenerate SSL certificates.
	*	--http — Run in HTTP-only mode (no HTTPS).
	*	-h — Display help message.

Examples

1. Default HTTPS Mode:

bin/start -a 192.168.179.21

2. HTTP-Only Mode:

bin/start --http

3. Specify Admin IPs and Ports:

bin/start -p 8080 -s 8443 -a "192.168.0.1,10.0.0.1"

4. Reset SSL Certificates:

bin/start -r

Access the Server

• HTTP: http://localhost:1337
• HTTPS: https://localhost

How It Works

1. Dependency Check: Ensures Ruby, Bundler, and mkcert are installed.
2. SSL Certificate Management: Verifies or regenerates certificates as needed.
3. Server Startup: Launches a Puma server with configurable HTTP/HTTPS endpoints.

For debugging or manual configuration, check the scripts in bin/helpers.

Why

hat

A bit about adding new stuff to the admin and client pages (The soon-to-be modules)

We use erb templates for the views, and JavaScript for the behavior. The system uses WebSocket connections for real-time communication, with the WebSocketUI class handling the base connection setup. Admin and client pages extend this functionality through their respective index.js files.

Where things live rn

Key directories for module development:

public/
├── js/
│   ├── admin/           # Admin interface behaviors
│   │   ├── index.js     # Main admin page logic
│   │   └── connected_clients.js
│   ├── client/          # Client interface behaviors 
│   │   └── index.js     # Main client page logic
│   └── lib/             # Shared WebSocket infrastructure
│       ├── websocket-ui.js # the front-facing API for the WebSocket connection
│       ├── litecable-connection.js # important to understand, but you probably won't need to modify
│       └── websocket-connection.js # same as above
├── css/
│   └── admin/          # Admin-specific styles
views/
├── layout.erb        # Base layout for all pages - this is where the global stuff like header and footer go, as well as all the css (for now)
├── admin/             # Admin page templates
│   ├── index.erb      # Main admin interface
│   └── _connected_clients.erb # This is what's called a partial, and is included in index.erb
└── index.erb         # Client page 

💎 Adding New Features 💎

See thesimple Step-by-Step Guide to Adding a New Admin-to-Client Communication Feature for detailed instructions on implementing a simple feature! (This will be updated as the module system is implemented)

---

The rest is a bit more complicated, but still useful to know.

Note about client view and logic: Yes, the js for the client lives under public/js/client, but the view is in views/index.erb. This was less confusing than the alternative, and the client view IS the / route, so it makes sense.

Understanding Communication Flow

• The system uses WebSocket connections through LiteCableConnection for real-time communication.
• The WebSocketUI class (in public/js/lib/websocket-ui.js) handles the base connection setup and manages interactions specific to Admin or Client roles.
• The WebSocketConnection class (in public/js/lib/websocket-connection.js) provides the low-level WebSocket functionality, including connection management, message handling, and reconnection logic.
• Admin and client pages extend this functionality through their respective index.js files

How They Interact:

1. WebSocketConnection establishes the foundational WebSocket connection to the server and ensures messages are transmitted and received properly.

2. LiteCableConnection extends WebSocketConnection to include protocol-specific behavior, such as subscribing to channels and processing incoming messages according to the LiteCable framework.

3. WebSocketUI builds on LiteCableConnection, adding role-specific logic and integrating with the user interface for Admin or Client pages.

   By layering these components, the system ensures a clear separation of concerns: low-level WebSocket handling (WebSocketConnection), protocol-specific functionality (LiteCableConnection), and UI integration (WebSocketUI).

4. Key Files for Development: To add new features, you'll primarily work with:

   • views/admin/index.erb - Admin interface
   • views/index.erb - Client interface
   • public/js/admin/index.js - Admin behavior
   • public/js/client/index.js - Client behavior

5. Helpful Development Context: When working with AI assistants or seeking help, share these files:

   • The relevant view template (.erb file)
   • The corresponding JavaScript (.js file)
   • If modifying styles, the relevant CSS
   • For WebSocket issues, include the relevant lib/ files

Future Module System

The platform is transitioning to a modular system where features will be organized as self-contained modules in the modules/ directory. Each module will contain its own admin and client components, making development more structured and isolated.

Stay tuned for updates as we enhance the module development experience, for you, the glorious module developer, whose every whim is our command, and whose every wish is our desire