instructions.md

LORA-OPERATOR Operations & Integration Instructions

This document provides setup, compilation, and execution instructions for the LORA-OPERATOR repository. The instructions are split into two target audiences: Human Operators and AI Agents/Subagents.

---

🧑‍💻 1. Instructions for Human Operators

A. Prerequisites

1. Python 3.8+ must be installed.
2. Install dependencies using:

   pip install -r requirements.txt
   

3. To run in Serial mode, ensure you have connected a compatible LoRa concentrator module (e.g. RAK Wireless) via USB/UART and know its COM port (on Windows, e.g. COM3) or device path (on Linux, e.g. /dev/ttyUSB0).

B. Local Compilation (If modifying the C core)

The repository contains a precompiled Windows dynamic library (cuneiform_u_v3.dll). If you make changes to the C library or compile on other operating systems:

• Windows (MinGW/gcc):

  gcc -O3 -shared -fPIC -o cuneiform_u_v3.dll cuneiform_u_v3_wrapper.c
  

• Linux (gcc):

  gcc -O3 -shared -fPIC -o libcuneiform_u_v3.so cuneiform_u_v3_wrapper.c
  

• macOS (clang):

  clang -O3 -shared -fPIC -o libcuneiform_u_v3.dylib cuneiform_u_v3_wrapper.c
  

C. Execution Methods (UDP Simulation)

To test the transmitter and receiver locally over UDP without hardware:

1. Start the Receiver Node:

   python RakMiner-B2.py --mode udp --ip 0.0.0.0 --port 50001
   

2. Start the Transmitter Node: (In another terminal window)

   python RakMiner-A1.py --mode udp --ip 127.0.0.1 --port 50001
   

If successful, both terminals will display: [+] Cuneiform-U v3 native acceleration loaded successfully! (Yang Mode) And the receiver will output: [+] Payload checksum verified successfully! Lossless path confirmed. [OK] [VERIFICATION] Multi-Language runtime FFI structures validated.

D. Execution Methods (LoRa Serial Hardware)

For real LoRa wireless communication using serial AT commands:

1. Start the Receiver AT Listener:

   python RakMiner-B2.py --mode serial --device /dev/ttyUSB0 --baud 115200
   

2. Start the Transmitter AT Command broadcaster:

   python RakMiner-A1.py --mode serial --device /dev/ttyUSB1 --baud 115200
   

---

🤖 2. Instructions for AI Agents and Code Generators

When parsing, refactoring, or integrating this repository, adhere strictly to the following mathematical, structural, and interface boundaries.

A. Shared Library Export Interfaces (ctypes)

The compiled binary exposes two dynamic library function interfaces. The definitions mapped to python must match exactly:

Concept6D C-Struct Definition:

typedef struct {
    uint8_t domain;       /* 0-15 */
    uint8_t subdomain;    /* 0-15 */
    uint8_t operation;    /* 0-15 */
    uint8_t modality;     /* 0-15 */
    uint8_t depth;        /* 0-15 */
    uint8_t polarity;     /* 0-15 */
} Concept6D;

Mapped in Python ctypes as:

class Concept6D(ctypes.Structure):
    _fields_ = [
        ("domain", ctypes.c_uint8),
        ("subdomain", ctypes.c_uint8),
        ("operation", ctypes.c_uint8),
        ("modality", ctypes.c_uint8),
        ("depth", ctypes.c_uint8),
        ("polarity", ctypes.c_uint8),
    ]

Function Bindings:

• Encode API:

  lib.cuneiform_u_v3_encode_dll.argtypes = [
      ctypes.POINTER(Concept6D), ctypes.c_uint32,
      ctypes.POINTER(ctypes.c_uint8), ctypes.c_uint32,
      ctypes.c_uint32, ctypes.c_uint32
  ]
  lib.cuneiform_u_v3_encode_dll.restype = ctypes.c_int
  

• Decode API:

  lib.cuneiform_u_v3_decode_dll.argtypes = [
      ctypes.POINTER(ctypes.c_uint8), ctypes.c_uint32,
      ctypes.POINTER(Concept6D), ctypes.c_uint32,
      ctypes.c_uint32, ctypes.c_uint32
  ]
  lib.cuneiform_u_v3_decode_dll.restype = ctypes.c_int
  

B. Protocol Packaging Specifications

• XOR-FEC Frames: Payload packets are padded to 252 data bytes + 3 byte header (SYNC_MARKER (0xBB), frame_index, total_frames) to create 255 byte physical packets matching LoRa hardware channel constraints.
• Metadata Signature Format: META:num_concepts:payload_hash:compressed_len
  • AI agents parsing the stream must extract compressed_len to trim the padded packet back to the exact compressed bitstream size before verifying the SHA-256 payload_hash and calling cuneiform_u_v3_decode_dll.

C. State Constraints (Radical Predictor)

• The transition count tables (trans_rc, trans_rf, trans_ra) are statically capped at MAX_TRANSITIONS = 256 transition elements. The model state predictor must maintain zero heap reallocation to be memory-safe on low-RAM microcontrollers.

D. Automated Verification Target Anchors

Scripts verifying execution output must check for the following exact stdout string sequences:

1. [+] Cuneiform-U v3 native acceleration loaded successfully! (Yang Mode) — confirms ctypes loaded the DLL.
2. [+] Payload checksum verified successfully! Lossless path confirmed. [OK] — confirms hash verification and trimming.
3. [VERIFICATION] Multi-Language runtime FFI structures validated. — confirms mathematical parity has been preserved.