cortexforge 0.1.0__py3-none-any.whl

cortexforge/forge/utils/sigmf/sigmf_annotations.py

@@ -0,0 +1,90 @@
+import math
+
+from cortexforge.forge.utils.node_layout import distance
+from cortexforge.forge.utils.node_identity import get_node_name
+from cortexforge.forge.utils.compute_baseline import MIN_LINEAR_POWER, measure_window_power
+
+
+def make_sigmf_annotations(annotations):
+    return sorted(annotations, key=lambda a: a["core:sample_start"])
+
+
+def theoretical_bandwidth_hz(ev):
+    modulation = ev["modulation"].upper()
+    symbol_rate = float(ev["symbol_rate"])
+    rolloff = float(ev["rolloff"])
+
+    # Default occupied RF bandwidth.
+    bw = (1.0 + rolloff) * symbol_rate
+
+    if modulation == "AM-SSB":
+        return 0.5 * bw
+    # Règle de Carson
+    if modulation == "FM":
+        sample_rate = float(ev["sample_rate_sps"])
+        freq_dev_hz = min(symbol_rate * 0.25, sample_rate * 0.20)
+        message_bw = 0.5 * bw
+        return 2.0 * (freq_dev_hz + message_bw)
+
+    return bw
+
+
+def timeline_to_sigmf_annotations(
+    events, rx_sample_rate, rx_uhd_t0, tx_center_freq, tx_gain, rx_data_path=None, baseline_stat=None
+):
+    ann = []
+    baseline_mean_power = None
+    if baseline_stat is not None:
+        baseline_mean_power = float(baseline_stat.get("mean_power", 0.0))
+
+    for ev in events:
+        start = int((ev["t_start_s"] - rx_uhd_t0) * rx_sample_rate)
+        count = int(ev["duration_s"] * rx_sample_rate)
+
+        modulation = ev["modulation"].upper()
+        bw = theoretical_bandwidth_hz(ev)
+        f0 = tx_center_freq
+
+        if modulation == "AM-SSB":
+            f_low = f0
+            f_high = f0 + bw
+        else:
+            f_low = f0 - bw / 2.0
+            f_high = f0 + bw / 2.0
+
+        annotation = {
+            "core:sample_start": start,
+            "core:sample_count": count,
+            "core:freq_lower_edge": f_low,
+            "core:freq_upper_edge": f_high,
+            "core:label": ev["modulation"],
+            "cortexforge:transmitter": ev["radio"],
+            "cortexforge:distance_m": distance(ev["radio"], get_node_name()),
+            "cortexforge:tx_gain_db": tx_gain,
+            "cortexforge:amplitude": ev["amplitude"],
+            "cortexforge:symbol_rate": ev["symbol_rate"],
+            "cortexforge:rolloff": ev["rolloff"],
+        }
+
+        if rx_data_path is not None and baseline_mean_power is not None and start >= 0 and count > 0:
+            try:
+                burst_stats = measure_window_power(
+                    rx_data_path,
+                    sample_start=start,
+                    sample_count=count,
+                )
+                total_mean_power = burst_stats["mean_power"]
+                signal_mean_power = max(total_mean_power - baseline_mean_power, MIN_LINEAR_POWER)
+                annotation["cortexforge:rx_total_power_dbfs"] = burst_stats["power_dbfs"]
+                annotation["cortexforge:rx_signal_power_dbfs"] = (
+                    10.0 * math.log10(signal_mean_power / 2.0)
+                )
+                annotation["cortexforge:snr_db"] = 10.0 * math.log10(
+                    signal_mean_power / max(baseline_mean_power, MIN_LINEAR_POWER)
+                )
+            except ValueError:
+                pass
+
+        ann.append(annotation)
+
+    return make_sigmf_annotations(ann)

cortexforge/forge/utils/sigmf/sigmf_captures.py

@@ -0,0 +1,21 @@
+from datetime import datetime, timezone
+
+from cortexforge.forge.utils.node_identity import get_node_name
+
+
+def make_sigmf_captures(center_freq: float, gain: float, hardware: str, stat):
+    return [
+        {
+            "core:datetime": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+            "core:frequency": float(center_freq),
+            "core:sample_start": 0,
+            "core:hw": hardware,
+            "cortexforge:node": get_node_name(),
+            "cortexforge:gain": gain,
+            "cortexforge:baseline": {
+                "sample_start": stat["skip_samples"],
+                "sample_count": stat["win_samples"],
+                "power_dbfs": stat["power_dbfs"],
+            },
+        }
+    ]

cortexforge/forge/utils/sigmf/sigmf_global.py

@@ -0,0 +1,13 @@
+from cortexforge.forge.utils.sigmf.hash import _sha512_hex
+
+
+def make_sigmf_global(author: str, sample_rate: float, data_path, description: str):
+    return {
+        "core:author": author,
+        "core:description": description,
+        "core:recorder": "CorteXForge",
+        "core:datatype": "cf32_le",
+        "core:sample_rate": float(sample_rate),
+        "core:data_file": data_path.name,
+        "core:sha512": _sha512_hex(data_path),
+    }

cortexforge/forge/utils/sigmf_writer.py

@@ -0,0 +1,58 @@
+from json import dumps
+from pathlib import Path
+
+from cortexforge.forge.utils.sigmf.sigmf_annotations import make_sigmf_annotations
+from cortexforge.forge.utils.sigmf.sigmf_captures import make_sigmf_captures
+from cortexforge.forge.utils.sigmf.sigmf_global import make_sigmf_global
+
+
+def write_sigmf(
+    base_path: str,
+    data_file: str,
+    sample_rate: float,
+    center_freq: float,
+    gain: float,
+    stat,
+    annotations,
+    hardware: str,
+    description: str = "CorteXForge capture",
+    author: str = "CorteXForge",
+):
+    """
+    base_path: path without extension
+    data_file: existing IQ file path (fc32 raw)
+    Creates:
+      - base_path.sigmf-data
+      - base_path.sigmf-meta
+    """
+    base = Path(base_path)
+    data_src = Path(data_file)
+
+    meta_path = base.with_suffix(".sigmf-meta")
+    data_path = base.with_suffix(".sigmf-data")
+
+    # Move the data to .sigmf-data if needed
+    if data_src.resolve() != data_path.resolve():
+        data_path.parent.mkdir(parents=True, exist_ok=True)
+        data_src.replace(data_path)
+
+
+    meta = {
+        "global": make_sigmf_global(
+            author=author,
+            sample_rate=sample_rate,
+            data_path=data_path,
+            description=description,
+        ),
+        "captures": make_sigmf_captures(
+            center_freq=center_freq,
+            gain=gain,
+            hardware=hardware,
+            stat=stat,
+        ),
+        "annotations": make_sigmf_annotations(annotations),
+    }
+
+    meta_path.parent.mkdir(parents=True, exist_ok=True)
+    meta_path.write_text(dumps(meta, indent=2))
+    return str(data_path), str(meta_path)

cortexforge/forge/utils/sync_barrier/rx_barrier_server.py

@@ -0,0 +1,46 @@
+import json
+import time
+import zmq
+from logging import getLogger
+from cortexforge.forge.utils.sync_barrier.sync_config import SyncConfig
+
+logger = getLogger(__name__)
+
+
+class RxBarrierServer:
+    def __init__(self, cfg: SyncConfig):
+        self.cfg = cfg
+        self.ctx = zmq.Context.instance()
+
+        self.rep = self.ctx.socket(zmq.REP)
+        self.rep.bind(f"tcp://*:{cfg.port_reg}")
+        logger.info("[RX][REP] bind tcp://*:%s", cfg.port_reg)
+
+
+        self.pub = self.ctx.socket(zmq.PUB)
+        self.pub.bind(f"tcp://*:{cfg.port_pub}")
+        logger.info("[RX][PUB] bind tcp://*:%s", cfg.port_pub)
+
+        self.registered = set()
+        
+
+    def wait_for_all(self):
+        logger.info("[RX] Waiting for %d TX registrations...", self.cfg.expected_tx)
+        while len(self.registered) < self.cfg.expected_tx:
+            raw = self.rep.recv()
+            now = time.time()
+            logger.info("[RX][REP][recv %.6f] %r", now, raw)
+
+            data = json.loads(raw.decode("utf-8"))
+            node = data.get("node", "unknown")
+            typ = data.get("type")
+            logger.info("[RX] HELLO from node=%s type=%s", node, typ)
+
+            self.registered.add(node)
+            reply = {"ok": True, "registered": sorted(self.registered)}
+            self.rep.send_string(json.dumps(reply))
+            logger.info("[RX][REP][send %.6f] %s", time.time(), reply)
+
+    def broadcast(self, payload: dict) -> None:
+        logger.info("[RX][PUB] broadcast %s", payload)
+        self.pub.send_string(json.dumps(payload))

cortexforge/forge/utils/sync_barrier/sync_config.py

@@ -0,0 +1,8 @@
+from dataclasses import dataclass
+
+@dataclass
+class SyncConfig:
+    server_host: str
+    port_reg: int = 5555
+    port_pub: int = 5556
+    expected_tx: int = 3

cortexforge/forge/utils/sync_barrier/tx_barrier_client.py

@@ -0,0 +1,38 @@
+import json
+import time
+import zmq
+from logging import getLogger
+from cortexforge.forge.utils.sync_barrier.sync_config import SyncConfig
+
+logger = getLogger(__name__)
+
+
+class TxBarrierClient:
+    def __init__(self, cfg: SyncConfig, node_name: str):
+        self.cfg = cfg
+        self.node_name = node_name
+        self.ctx = zmq.Context.instance()
+
+        self.req = self.ctx.socket(zmq.REQ)
+        ep_req = f"tcp://{cfg.server_host}:{cfg.port_reg}"
+        self.req.connect(ep_req)
+        logger.info("[TX:%s][REQ] connect %s", node_name, ep_req)
+
+        self.sub = self.ctx.socket(zmq.SUB)
+        ep_sub = f"tcp://{cfg.server_host}:{cfg.port_pub}"
+        self.sub.connect(ep_sub)
+        self.sub.setsockopt_string(zmq.SUBSCRIBE, "")
+        logger.info("[TX:%s][SUB] connect %s + SUBSCRIBE ''", node_name, ep_sub)
+
+    def register(self):
+        msg = {"type": "HELLO", "node": self.node_name}
+        self.req.send_string(json.dumps(msg))
+        logger.info("[TX:%s][REQ][send %.6f] %s", self.node_name, time.time(), msg)
+
+        rep = self.req.recv_string()
+        logger.info("[TX:%s][REQ][recv %.6f] %s", self.node_name, time.time(), rep)
+
+    def wait_broadcast(self):
+        raw = self.sub.recv_string()
+        logger.info("[TX:%s][SUB][recv %.6f] %s", self.node_name, time.time(), raw)
+        return json.loads(raw)

cortexforge/forge/utils/uhd_time.py

@@ -0,0 +1,15 @@
+import time
+from gnuradio import uhd
+
+def wait_for_pps_edge(usrp_block, poll_s=0.0001):
+    last = usrp_block.get_time_last_pps().get_real_secs()
+    while True:
+        time.sleep(poll_s)
+        cur = usrp_block.get_time_last_pps().get_real_secs()
+        if cur != last:
+            return cur
+
+def arm_time_reset_next_pps(usrp_block):
+    wait_for_pps_edge(usrp_block)
+    usrp_block.set_time_next_pps(uhd.time_spec(0.0))
+    wait_for_pps_edge(usrp_block)

cortexforge/planner/generators/cortexlab_scenario.py

@@ -0,0 +1,44 @@
+import logging
+from pathlib import Path
+from typing import List
+
+from yaml import safe_dump
+
+logger = logging.getLogger(__name__)
+
+
+def generate_cortexlab_scenario(
+    nodes: List[str],
+    duration: int,
+    image: str,
+    rx_command: str,
+    tx_command: str,
+    description: str = "Dataset Generator",
+    output_path: str = "scenario.yaml",
+):
+    data = {"description": description, "duration": duration, "nodes": {}}
+    rx_node = nodes[0]
+    data["nodes"][rx_node.replace("mnode", "node")] = {
+        "container": [
+            {
+                "image": image,
+                "command": rx_command,
+            }
+        ]
+    }
+    for node in nodes[1:]:
+        data["nodes"][node.replace("mnode", "node")] = {
+            "container": [
+                {
+                    "image": image,
+                    "command": tx_command,
+                }
+            ]
+        }
+
+    out_path = Path(output_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with out_path.open("w") as f:
+        safe_dump(data, f, sort_keys=False)
+
+    logger.info(f"Cortexlab scenario written to {out_path}")

cortexforge/planner/generators/experiment_scenario.py

@@ -0,0 +1,191 @@
+import random
+from typing import List
+
+import pandas as pd
+
+
+class ExperimentScenario:
+    """
+    Generate a pseudo-random experiment schedule as a CSV.
+
+    Constraints:
+    - Signals start no earlier than warmup_time.
+    - Signals must end before or at the total experiment duration.
+    - The receiver node and its params are fixed for the whole experiment.
+    """
+
+    def __init__(
+        self,
+        nodes: List[str],
+        duration: float,
+        rx_sample_rate: int,
+        warmup_time: float = 2.0,
+    ):
+        if len(nodes) < 2:
+            raise ValueError("You must provide at least one RX node and one TX node.")
+
+        if warmup_time >= duration:
+            raise ValueError("warmup_time must be strictly less than total duration.")
+
+        self.nodes = nodes
+        self.duration = duration
+        self.rx_sample_rate = rx_sample_rate
+        self.warmup_time = warmup_time
+        self.rx_node = nodes[0]
+        self.tx_nodes = nodes[1:]
+
+        self.modulations = [
+            "AM-DSB",
+            "AM-SSB",
+            "FM",
+            "OOK",
+            "PAM4",
+            "4ASK",
+            "8ASK",
+            "BPSK",
+            "QPSK",
+            "8PSK",
+            "16PSK",
+            "32PSK",
+            "CPFSK",
+            "GFSK",
+            "16QAM",
+            "32QAM_RECT",
+            "32QAM_CROSS",
+            "64QAM",
+            "128QAM_RECT",
+            "128QAM_CROSS",
+            "256QAM",
+        ]
+
+        self.duration_range_s = (0.002, 0.020)
+
+    @staticmethod
+    def _intervals_overlap(
+        start_a: float,
+        duration_a: float,
+        start_b: float,
+        duration_b: float,
+    ) -> bool:
+        end_a = start_a + duration_a
+        end_b = start_b + duration_b
+        return start_a < end_b and start_b < end_a
+
+    def _find_non_overlapping_start(
+        self,
+        signal_duration: float,
+        scheduled_intervals: List[tuple],
+        rng: random.Random,
+        max_attempts: int = 1000,
+    ) -> float:
+        latest_start = self.duration - signal_duration
+        if latest_start < self.warmup_time:
+            raise ValueError(
+                "Signal duration is too large for the available experiment window."
+            )
+
+        for _ in range(max_attempts):
+            candidate_start = round(rng.uniform(self.warmup_time, latest_start), 6)
+
+            has_overlap = any(
+                self._intervals_overlap(
+                    candidate_start,
+                    signal_duration,
+                    existing_start,
+                    existing_duration,
+                )
+                for existing_start, existing_duration in scheduled_intervals
+            )
+
+            if not has_overlap:
+                return candidate_start
+
+        raise RuntimeError(
+            "Unable to place a non-overlapping signal. "
+            "Try reducing n_signals, reducing signal durations, "
+            "or increasing the experiment duration."
+        )
+
+    def generate_table(
+        self,
+        n_signals: int = 100,
+        allow_overlap: bool = True,
+        seed: int | None = None,
+    ) -> pd.DataFrame:
+        """
+        Generate a pandas DataFrame with the experiment timeline.
+
+        Args:
+            n_signals: Number of signals to generate.
+            allow_overlap: If False, generated signals will not overlap in time.
+            seed: Optional seed for reproducibility.
+        """
+        rng = random.Random(seed)
+
+        rows = []
+        scheduled_intervals = []
+
+        for _ in range(n_signals):
+            signal_node = rng.choice(self.tx_nodes)
+            signal_duration = round(rng.uniform(*self.duration_range_s), 6)
+            signal_modulation = rng.choice(self.modulations)
+
+            if allow_overlap:
+                signal_start_time = round(
+                    rng.uniform(self.warmup_time, self.duration - signal_duration), 6
+                )
+            else:
+                signal_start_time = self._find_non_overlapping_start(
+                    signal_duration=signal_duration,
+                    scheduled_intervals=scheduled_intervals,
+                    rng=rng,
+                )
+                scheduled_intervals.append((signal_start_time, signal_duration))
+
+            rows.append(
+                {
+                    "radio": signal_node,
+                    "start_time": signal_start_time,
+                    "duration_s": signal_duration,
+                    "modulation": signal_modulation,
+                    "amplitude": 0.5,
+                    "roll_off": 0.35,
+                    "symbol_rate": 3_125_000,
+                    "sample_rate_sps": 25_000_000,
+                }
+            )
+
+        df = pd.DataFrame(
+            rows,
+            columns=[
+                "radio",
+                "start_time",
+                "duration_s",
+                "modulation",
+                "amplitude",
+                "roll_off",
+                "symbol_rate",
+                "sample_rate_sps",
+            ],
+        )
+
+        df = df.sort_values("start_time").reset_index(drop=True)
+        return df
+
+    def to_csv(
+        self,
+        output_path: str,
+        n_signals: int = 100,
+        allow_overlap: bool = True,
+        seed: int | None = None,
+    ):
+        """
+        Generate the table and write it directly to a CSV file.
+        """
+        df = self.generate_table(
+            n_signals=n_signals,
+            allow_overlap=allow_overlap,
+            seed=seed,
+        )
+        df.index.name = "id"
+        df.to_csv(output_path)

cortexforge/planner/main.py

@@ -0,0 +1,57 @@
+from cortexforge.cli.planner import parse_args
+from cortexforge.planner.generators.cortexlab_scenario import (
+    generate_cortexlab_scenario,
+)
+from cortexforge.planner.generators.experiment_scenario import ExperimentScenario
+from cortexforge.utils.loader import load_nodes
+from cortexforge.utils.logger import setup_logger
+
+logger = setup_logger()
+
+
+def main() -> None:
+    logger.info("Starting scenario generation...")
+    args = parse_args()
+    nodes = load_nodes(args.nodes_path)
+
+    scenario = ExperimentScenario(
+        nodes=nodes,
+        duration=args.duration,
+        rx_sample_rate=args.rx_sample_rate,
+    )
+
+    df = scenario.generate_table(n_signals=100, allow_overlap=args.overlapping, seed=42)
+    print(df.head())
+
+    scenario.to_csv(
+        "configs/timeline.csv", n_signals=100, allow_overlap=args.overlapping, seed=42
+    )
+
+    generate_cortexlab_scenario(
+        nodes=nodes,
+        duration=args.duration + 30,
+        image="ghcr.io/andreaj42/cortexforge:latest",
+        rx_command=(
+            f'bash -lc "cortexforge-forge rx '
+            f"--duration {args.duration} "
+            f"--frequency {args.rx_frequency} "
+            f"--gain {args.rx_gain} "
+            f"--sample-rate {args.rx_sample_rate} "
+            f"--output-path /cortexlab/homes/{args.username}/out/ "
+            f'--timeline /cortexlab/homes/{args.username}/timeline.csv"'
+        ),
+        tx_command=(
+            f'bash -lc "cortexforge-forge tx '
+            f"--timeline /cortexlab/homes/{args.username}/timeline.csv "
+            f"--record-node {nodes[0]} "
+            f"--frequency {args.rx_frequency} "
+            f'--gain {args.rx_gain}"'
+        ),
+        description="Dataset Generator",
+        output_path="configs/scenario.yaml",
+    )
+    logger.info("Scenario generation completed.")
+
+
+if __name__ == "__main__":
+    main()

cortexforge/utils/loader.py

@@ -0,0 +1,35 @@
+import logging
+from pathlib import Path
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+def load_yaml(path: Path) -> dict:
+    """Load a YAML file and return its contents as a dictionary."""
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    with path.open("r") as f:
+        return yaml.safe_load(f)
+
+
+def load_nodes(path: Path = "configs/nodes.yaml") -> list[str]:
+    """
+    Load node IDs from a YAML configuration configs/nodes.yaml file.
+
+    Expected YAML format:
+    nodes:
+      - id: mnode1
+      - id: mnode2
+      ...
+    """
+    data = load_yaml(path)
+
+    nodes = [node["id"] for node in data["nodes"]]
+
+    if len(nodes) < 2:
+        raise ValueError("At least two nodes are required")
+
+    logger.info("Loaded %d nodes: %s", len(nodes), nodes)
+    return nodes

cortexforge/utils/logger.py

@@ -0,0 +1,21 @@
+import logging
+
+
+def setup_logger(level: int = logging.INFO) -> logging.Logger:
+    """
+    Configure logging for CorteXforge.
+    """
+    logger = logging.getLogger()
+    logger.setLevel(level)
+
+    if not logger.handlers:
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(level)
+        formatter = logging.Formatter(
+            "[%(asctime)s] [%(levelname)s][%(filename)s]: %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        console_handler.setFormatter(formatter)
+        logger.addHandler(console_handler)
+
+    return logger

cortexforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: cortexforge
+Version: 0.1.0
+Summary: RF generator dataset based on SLICES/CorteXlab
+Author-email: Andrea Joly <andrea.joly@inria.fr>
+Requires-Python: >=3.10
+Provides-Extra: planner
+Requires-Dist: numpy==2.3.4; extra == "planner"
+Requires-Dist: pandas==2.3.3; extra == "planner"
+Requires-Dist: python-dateutil==2.9.0.post0; extra == "planner"
+Requires-Dist: pytz==2025.2; extra == "planner"
+Requires-Dist: PyYAML==6.0.3; extra == "planner"
+Requires-Dist: six==1.17.0; extra == "planner"
+Requires-Dist: tzdata==2025.2; extra == "planner"
+Provides-Extra: forge
+Requires-Dist: sigmf==1.2.12; extra == "forge"