Metadata-Version: 2.4
Name: armex
Version: 0.0.1
Summary: Advanced secure dual-key launch system (ARMEX)
Author: BLACKBIRT
License: Shadowlock
Description-Content-Type: text/markdown
License-File: LICENCE.md
Dynamic: license-file

# ✅ **ARMEX — Dual-Key Launch Control System (Plugin-Based)**

ARMEX is a modular command-line framework with a secure dual-key launch system plugin designed for Raspberry Pi or simulation environments.

It uses a plugin architecture, so additional tools can be added easily.

The `launcher` plugin implements a realistic two-key authorization system, physical button confirmation, timed launch windows, and full event logging.

---

# ⭐ **Features**

### ✔ Plugin-based architecture

Every command is a plugin under `armex/plugins/`.

### ✔ Dual-key arming system

Both hardware keys must be turned within a 0.5s window.

### ✔ Physical launch button confirmation

Launch must be confirmed twice:

1. Pre-launch button confirmation
2. Actual launch activation during the countdown

### ✔ One-time launch code per session

A 6-digit random code is shown at startup.

### ✔ Admin override

A static admin code (DDMMYYYY) bypasses the launch code.

### ✔ Operator identity logging

Operator name and ID are stored with each launch record.

### ✔ Full session logging

Everything is recorded:

* launch code
* operator info
* arming success/fail
* abort reasons
* timeouts
* launch confirmation
* reset events
* final exit status

Logs are stored in the `launchlogs/` directory.

### ✔ Simulation mode

Run the launcher without GPIO hardware:

<pre class="overflow-visible!" data-start="1497" data-end="1523"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre!"><span><span>armex</span><span> launcher sim
</span></span></code></div></div></pre>

Keys/buttons are controlled with:

* **1** = KEY1
* **2** = KEY2
* **3** = LAUNCH

### ✔ Safety handling

* CTRL-C is disabled (prevents partial logs or dirty GPIO state)
* Only closing the terminal window fully terminates the process
* “X” at any prompt cleanly aborts the session and safely writes logs

---

# 📦 **Installation**

From PyPI:

<pre class="overflow-visible!" data-start="1877" data-end="1904"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre! language-sh"><span><span>pip install armex
</span></span></code></div></div></pre>

Upgrade:

<pre class="overflow-visible!" data-start="1916" data-end="1953"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre! language-sh"><span><span>pip install --upgrade armex
</span></span></code></div></div></pre>

---

# 🚀 **Running the Launcher**

### **Normal hardware mode:**

<pre class="overflow-visible!" data-start="2022" data-end="2046"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre! language-sh"><span><span>armex launcher
</span></span></code></div></div></pre>

### **Simulation mode (PC, laptop, or mobile IDE):**

<pre class="overflow-visible!" data-start="2102" data-end="2130"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre! language-sh"><span><span>armex launcher sim
</span></span></code></div></div></pre>

---

# 🧪 **Launcher Sequence Overview**

### 1. Launch Code

A random 6-digit launch code is displayed.

Operator must type it or the admin override.

### 2. Operator Authentication

Operator enters:

* Name
* Personnel ID

Both are logged.

### 3. Pre-Launch Confirmation

Operator must press the  **launch button once** .

### 4. Dual-Key ARMED State

Both physical keys must be turned to ARM within a 0.5 second window.

Failure → system reset → new launch code required.

### 5. Launch Window

A red countdown bar displays 30 seconds.

Operator must press the launch button during this window.

Abort conditions:

* Key turned off
* Timeout
* Button pressed too early

Any abort forces a reset and new launch code.

### 6. Successful Launch

The system fires, logs completion, and requires:

* KEY1 off
* KEY2 off
* launch button released

Then the session ends and logs close properly.

---

# 📂 **Log Files**

Logs are stored automatically in:

<pre class="overflow-visible!" data-start="3105" data-end="3124"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre!"><span><span>launchlogs/
</span></span></code></div></div></pre>

Example files:

<pre class="overflow-visible!" data-start="3142" data-end="3186"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre!"><span><span>431955.txt
ADMIN_20251124_221530.txt
</span></span></code></div></div></pre>

Each file contains:

* Date & time
* Launch code or admin override
* Operator ID
* Arming steps
* Launch confirmation
* Reset events
* Final exit

---

# 🧩 **Plugin System**

To add a new command, create a file inside:

<pre class="overflow-visible!" data-start="3422" data-end="3444"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre!"><span><span>armex/plugins/
</span></span></code></div></div></pre>

Example:

<pre class="overflow-visible!" data-start="3456" data-end="3520"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre! language-python"><span><span>def</span><span></span><span>run</span><span>():
    </span><span>print</span><span>(</span><span>"My custom tool is running!"</span><span>)
</span></span></code></div></div></pre>

Then it appears automatically:

<pre class="overflow-visible!" data-start="3554" data-end="3576"><div class="contain-inline-size rounded-2xl relative bg-token-sidebar-surface-primary"><div class="sticky top-9"><div class="absolute end-0 bottom-0 flex h-9 items-center pe-2"><div class="bg-token-bg-elevated-secondary text-token-text-secondary flex items-center gap-4 rounded-sm px-2 font-sans text-xs"></div></div></div><div class="overflow-y-auto p-4" dir="ltr"><code class="whitespace-pre! language-sh"><span><span>armex mytool
</span></span></code></div></div></pre>

---

# 🔌 **Default GPIO Pin Mapping (BCM)**

| Function      | Pin |
| ------------- | --- |
| KEY1          | 17  |
| KEY2          | 27  |
| LAUNCH BUTTON | 22  |
| RED LED       | 5   |
| GREEN LED     | 6   |
| FIRE OUTPUT   | 13  |

---

# ⚠ Safety Notice

* CTRL-C is disabled to protect system state and logs
* Only close the terminal window (X) to fully stop the program
* Use a safe test environment before connecting anything real
* Simulation mode is strongly recommended before hardware deployment

---

# 📜 License

Shadowlock License v1.1

© 2025 — Ben Meulenbeld
