ko_center System User Documentation

Version: v0.70 (2026-08-01)
Type: PHP/Perl Web Application
Database: SQLite (ko_center.db3)
Location: /os/ai/io/ko_center.php

1. Overview

ko_center is a single-file web application that provides a centralized dashboard for managing and monitoring system resources. It uses SQLite as its backend database and generates HTML pages dynamically via PHP.

The system provides:

• LED indicator display — visual status indicators with configurable colors, speeds, and types (manual, date, cmd, null)
• Database grid views — sortable, filterable table views of any database table
• Reports — SQL-based reports with CSV and XML export
• Knowledge Base — CRUD operations for KB articles
• Certificate management — view and manage certificates
• Node/Host management — view and manage network nodes
• Hardware inventory — detailed hardware tracking
• Zoom viewer — interactive zoomable image viewer with hotspots
• Trigger endpoint — forces browser refresh when called by another user

2. Access & Login

Login

Access the system by navigating to the ko_center URL. If not logged in, the system presents a login form.

URL: http://<host>/ko_center/ko_center.php

Login credentials are validated against the hosts.allow file located at /os/ai/io/../safer/hosts.allow.

Once logged in, the user's role determines which features and data they can access.

Logout

Click the logout button (white icon) in the navigation bar to end your session.

3. Navigation & Interface

Button Squares

The main navigation bar provides quick access to all major features via button squares. Available buttons depend on user role:

4. URL Routing & Query Parameters

The system uses the q query parameter for routing. The parameter value is split by / to determine the page and sub-actions.

URL Format

ko_center.php?q=<page>/<action>/<id>

Routing Examples

5. LED Display System

The LED display system is the core visual component of ko_center. Each LED record represents a monitored item with configurable visual properties.

LED Record Fields

LED Types

LED Blinking

LEDs use animated GIF files for blinking effects. The GIF filename is constructed from the color and speed:

ani_colorspeed.gif

Example: ani_red1.gif (red, slow blink)

LED Detail View

Clicking an LED name navigates to the detail view (?q=detail/<name>), which shows associated hardware items, images, and metadata.

6. Database Grid Views

The grid system provides sortable, filterable table views of any database table. It supports pagination, column sorting, and inline editing.

Accessing Grid Views

ko_center.php?q=db/grid/<dbcode>/<table>

Or use the shortcut:

ko_center.php?q=grid?dbcode=<dbcode>&table=<table>

Grid Features

• Column sorting — click column headers to sort
• Pagination — navigate through large result sets
• Search/filter — filter rows by column values
• XML/CSV export — export grid data in multiple formats
• Inline editing — edit cell values directly in the grid

Supported Database Tables

The system supports multiple database files with role-based access:

• ko_center.db3 — Main center database (leds, randomus, ko_plans, ko_hw, etc.)
• koaac_kb.db3 — Knowledge Base database
• ko_center_certs.db3 — Certificates database

7. Reports

The reports system provides three types of report views:

SQL Report

Run custom SQL queries against the database and view results in a table.

ko_center.php?q=reports/sql

CSV Report

Export query results as CSV files for spreadsheet processing.

ko_center.php?q=reports/rpt/<rptcode>&fmt=header_csv

XML Report

Export query results as XML for programmatic consumption.

ko_center.php?q=kb/rpts/rpt_id&fmt=xml

Report Types

8. Knowledge Base

The Knowledge Base (KB) system allows users to create, view, and manage articles. KB entries are stored in the koaac_kb table in the ko_center.db3 database.

KB Table Schema

KB Actions

• List — ?q=kb — View all KB entries
• New — ?q=kb/new — Create a new article
• View — ?q=kb/view/<id> — Read an article
• Modify — ?q=kb/mod/<id> — Edit an article
• Reports — ?q=kb/rpts — View KB reports

9. Certificates

The certificate management system allows viewing and managing digital certificates stored in the ko_center_certs.db3 database.

Certificate Actions

• List — ?q=certs — View all certificates
• View — ?q=certs/view/<code> — View certificate details
• Reports — ?q=certs/rpts — Certificate status reports

10. Nodes / Hosts

The node management system tracks network nodes and hosts. Nodes are displayed with their status, location, and associated metadata.

Node Actions

• List — ?q=nodes — View all nodes
• Reports — ?q=nodes/rpts — Node reports

11. Hardware Inventory

The hardware inventory system tracks physical equipment with details such as model, serial number, IP address, HRC tag, and associated cabinet/location.

Hardware Actions

• List — ?q=hw — View all hardware
• Filter — ?q=hw&cab=cab1 — Filter by cabinet
• Filter — ?q=hw&item=item1 — Filter by item
• Filter — ?q=hw&sn=SN123 — Filter by serial number
• Filter — ?q=hw&ip=10.0.0.1 — Filter by IP address
• Filter — ?q=hw&hrctag=TAG123 — Filter by HRC tag

12. Plans

The plans system tracks project plans with steps, items, and status tracking.

Plan Actions

• List — ?q=plans — View all plans
• View — ?q=plans/view — View plan details
• Steps — ?q=plans/steps — View plan steps
• Items — ?q=plans/items — View plan items
• Reports — ?q=plans/reports — Plan reports

13. Tools

The tools section provides access to various system utilities:

Scrub

Data cleanup and maintenance tool.

ko_center.php?q=scrub

Upload

File upload utility for KB attachments and other files.

ko_center.php?q=upload

Zoom Viewer

Interactive zoomable image viewer with hotspot navigation.

ko_center.php?q=zoom/<code>/<type>/<rowid>

ZView

Full-screen zoom view with XML-based hotspot configuration.

ko_center.php?q=zview/<file>/<xml>

PTViewer

Panorama/tour viewer for 360-degree images.

ko_center.php?q=ptviewer

PTObject

Individual panorama object viewer.

ko_center.php?q=ptobject

14. Trigger / Auto-Refresh

The trigger system allows one browser to signal all other browsers to refresh their views. This is useful when one user makes a change that should be immediately visible to all other users.

How It Works

1. Browser A is viewing the ko_center dashboard
2. Browser B (or any client) calls ko_center.php?q=trigger
3. The trigger endpoint writes a timestamp to ko_trigger.dat
4. Browser A's JavaScript polling detects the new timestamp
5. Browser A automatically reloads the page

Trigger Endpoint

ko_center.php?q=trigger

The endpoint accepts an optional last_check parameter:

ko_center.php?q=trigger&last_check=2026-08-01 07:00:00

Response Format

{
  "triggered": true,
  "timestamp": "2026-08-01 07:05:00",
  "since": "2026-08-01 07:00:00"
}

Client-Side Polling

The client page includes JavaScript that polls the trigger endpoint every few seconds. When a new trigger is detected, the browser automatically reloads.

15. Database Schema

Main Database: ko_center.db3

Location: /os/ai/io/ko_center.db3 (39.6 MB)

Key Tables

leds_randomus Table

The leds_randomus table combines the schema of the leds table (all columns, with LED fields blank/NULL) with all columns from the randomus table. It contains only records from the randomus table (101 rows).

Creation script: /os/ai/io/new_leds.py

16. Key Files

Appendix A: Python ko_center.py

A Python Flask equivalent of ko_center.php has been created at /os/ai/io/ko_center.py. It provides the same core functionality:

• Flask-based web server (replaces PHP built-in server)
• Same ?q= URL routing
• SQLite database access via Python sqlite3 module
• Same HTML generation for all major views
• LED display, grid views, reports, KB, certs, nodes, HW, plans
• Login/logout session management
• Trigger endpoint (?q=trigger)
• Database table creation utilities

Running the Python version:

python3 /os/ai/io/ko_center.py

Then browse to http://localhost:5000

Appendix B: LED GIF Creation

The cr_leds.py script generates blinking LED GIF images using ImageMagick. For each color (red, yellow, blue, green, pink, orange, black, white, transparent) and each speed (0=no blink, 1=slow, 2=medium, 3=fast), it creates an animated GIF file.

Usage:

python3 cr_leds.py <static_image.png> <dynamic_image.png>

Output files:

led_<prefix>_red_0.gif   (no blink)
led_<prefix>_red_1.gif   (slow blink)
led_<prefix>_red_2.gif   (medium blink)
led_<prefix>_red_3.gif   (fast blink)
led_<prefix>_yellow_0.gif
...
led_<prefix>_trans_3.gif

There are 9 colors × 4 speeds = 36 GIF files per static image.