Initial import: ICE-NET research docs and Rust workspace (v0.4)
Some checks failed
rust-ci / checks (push) Has been cancelled
Some checks failed
rust-ci / checks (push) Has been cancelled
- Rust workspace: 7 library crates, icenetd CLI, icenet-city (Slint GUI) - Sim: fix false Delivered after a route cut, derive traffic class from payload size, per-link airtime slots (link capacity, queueing) - Docs: single docs/STATUS.md for all figures, remove v0.2/egui leftovers, drop unimplemented seed claims, uncheck store-and-forward - License: LGPL-3.0-or-later (LICENSE, LICENSES/GPL-3.0.txt)
This commit is contained in:
commit
2e61688eb3
141 changed files with 13993 additions and 0 deletions
45
docs/simulator/city_editor.md
Normal file
45
docs/simulator/city_editor.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# ICE-NET City Lab — интерактивный эмулятор города
|
||||
|
||||
## Назначение
|
||||
|
||||
Нативное окно Rust/Slint, где видны устройства и каналы связи.
|
||||
Первый GUI не зависит от реальных IP-адресов и может работать **офлайн**.
|
||||
|
||||
## Возможности стартового каркаса
|
||||
|
||||
- Нарисовать карту/граф, добавлять устройства и связи, видеть названия и типы.
|
||||
- Выбрать отправителя/получателя; отправить Text (малый) или Photo (Bulk).
|
||||
- Выбрать роль нового узла (Client/Relay/Backbone) и тип линка; подсветить последний маршрут.
|
||||
- Отключить/включить узел или ребро через боковую панель.
|
||||
- Продвинуть симуляционное время вручную (Step), посмотреть Queued/Delivered/Expired.
|
||||
- Изменить расположение устройств кликом/drag (проверено под X11/Xvfb).
|
||||
- Посмотреть выбранный маршрут и базовый журнал доставки.
|
||||
- Экспортировать `icenet-metrics.csv` и `icenet-scenario.json` кнопками в боковой панели.
|
||||
|
||||
## Не реализовано на старте
|
||||
|
||||
- Сценарии на 1000 узлов в GUI, загрузка сохранённого JSON обратно.
|
||||
- Настоящее позиционирование по GPS/радиосигналу, физика Fresnel, beamforming.
|
||||
- Моделирование interference, duty cycle, hidden terminals и настоящая передача файлов.
|
||||
- Релеи через смартфоны и реальный интернет.
|
||||
|
||||
## Как использовать при разработке алгоритмов
|
||||
|
||||
1. Реализовать новый `choose_path` в `icenet-routing`.
|
||||
2. Добавить тест в `crates/icenet-routing/tests/routing.rs`.
|
||||
3. Запустить city lab; сравнить Text vs Bulk на одном графе.
|
||||
4. Отключить быстрейшую связь; проверить корректный NO_ROUTE/QUEUED.
|
||||
5. Зафиксировать seed/топологию в scenario и сравнить метрики.
|
||||
|
||||
**Критично:** рисовалка не должна выполнять маршрутизацию внутри `ui.update()`;
|
||||
она передаёт запрос в `icenet-sim`, а рисует результат.
|
||||
|
||||
## Граница GUI (v0.3)
|
||||
|
||||
`ui/main.slint` показывает объекты из `VecModel`, фиксирует нажатия и drag.
|
||||
`src/main.rs` регистрирует callback-обработчики, `src/state.rs` изменяет
|
||||
`icenet-sim::City`, `src/view.rs` строит только визуальные модели.
|
||||
Обработчик **не** рассчитывает маршруты сам; алгоритм остался в `icenet-routing`.
|
||||
|
||||
GUI на Slint собран и проверен под X11/Xvfb: узлы, линии, drag, переключение
|
||||
устройств/линий и экспорт CSV/JSON. Полная проверка на Wayland-сессии — отдельный шаг.
|
||||
45
docs/simulator/event_model.md
Normal file
45
docs/simulator/event_model.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# Simulation engine: contract
|
||||
|
||||
## Состояния сообщения
|
||||
|
||||
`Queued -> InFlight -> Delivered`; `InFlight -> Queued` при потере пригодного маршрута;
|
||||
`Queued | InFlight -> Expired` по TTL. `Delivered` и `Expired` конечные.
|
||||
|
||||
- Есть `created_ms`, `expires_ms`, `first_route_ms`; `tick()` переводит просроченное сообщение в
|
||||
`Expired` и больше не доставляет его.
|
||||
- Прибытие в момент `due_ms <= expires_ms` — доставка, даже если один крупный шаг времени
|
||||
перескочил оба дедлайна (`tests/ttl.rs`).
|
||||
- **Ложный `Delivered` исключён.** Изменения топологии происходят между тиками, поэтому топология
|
||||
в `tick` держалась весь интервал. Доставка требует, чтобы все узлы маршрута были online, каждый
|
||||
линк включён, соединял нужные узлы и допускал класс. Иначе сообщение перепланируется или встаёт
|
||||
в `Queued` (`tests/city.rs`).
|
||||
|
||||
## Ёмкость линка
|
||||
|
||||
- На каждом линке календарь слотов эфира. Hop занимает `transfer_ms(bytes) + HOP_OVERHEAD_MS`.
|
||||
- Резервирование идёт по порядку отправки; следующий слот начинается не раньше конца предыдущего,
|
||||
а освободившиеся промежутки могут быть заняты. `due_ms` включает ожидание в очереди.
|
||||
- Перепланирование освобождает ещё не начатые слоты сообщения; уже начатый airtime считается
|
||||
потраченным. Истёкшее или потерявшее путь сообщение тоже освобождает будущие слоты.
|
||||
- Выбор пути **не** учитывает бэклог, а перепланирование начинает с источника — ограничения.
|
||||
- Метрики: `City::link_airtime_ms(kind)`, `City::link_backlog_ms(index)`, `slow_radio_airtime_ms`.
|
||||
|
||||
## События будущей DES
|
||||
|
||||
Сейчас время идёт шагами `tick`; полноценной очереди событий нет. План:
|
||||
|
||||
| Event | Поля |
|
||||
| --- | --- |
|
||||
| `Announce` | node_id, iface, ttl |
|
||||
| `LinkUp/LinkDown` | link_id, now_ms |
|
||||
| `Send` | source, dest, bytes, traffic_class |
|
||||
| `HopFinished` | message_id, hop_index |
|
||||
| `Ack` | message_id, kind |
|
||||
| `QueueExpire` | message_id, ttl |
|
||||
|
||||
## Детерминизм
|
||||
|
||||
- Одинаковые сценарий и последовательность действий дают одинаковый результат бит-в-бит
|
||||
(случайности нет; **`seed` не реализован**).
|
||||
- Ни один core алгоритм не вызывает `SystemTime` напрямую.
|
||||
- GUI не ускоряет модель при изменении частоты кадров.
|
||||
32
docs/simulator/metrics.md
Normal file
32
docs/simulator/metrics.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
# Метрики и честность моделирования
|
||||
|
||||
Цифры измерений — только в [STATUS](../STATUS.md).
|
||||
|
||||
## Минимальный набор
|
||||
|
||||
| Метрика | Смысл | Метод |
|
||||
| --- | --- | --- |
|
||||
| Delivery ratio | доставлено / создано | считать только `Delivered` |
|
||||
| `first_route_ms` p50/p95 | **абсолютная** метка симулированного времени первого пути | не задержка: вычитания `created_ms` пока нет |
|
||||
| Control airtime | эфир, занятый сообщениями класса Control по их маршрутам | сумма `transfer_ms + HOP_OVERHEAD_MS` по hop |
|
||||
| `slow_radio_airtime_ms` | эфир, зарезервированный на slow radio всеми сообщениями | календарь слотов линков |
|
||||
| Задержка поиска пути | реальное время CPU Dijkstra | `Instant` в `tests/scale.rs`, **debug**, не симуляция |
|
||||
| RAM | реальная память процесса | procfs/OS вне симуляции; на 1000 узлов не измерено |
|
||||
|
||||
`icenet_sim::metrics` считает состояния, delivery ratio, перцентили и airtime.
|
||||
`messages_csv` и `scenario_json` дают детерминированный экспорт.
|
||||
|
||||
## Условия воспроизводимости
|
||||
|
||||
- Источник кода/commit, дата, топология, link profile, последовательность действий.
|
||||
- Отдельно записать версию Rust и OS. `seed` не нужен, пока в модели нет случайности.
|
||||
- Минимум 3 сценария: пустой эфир, заполненный эфир, отключение backbone.
|
||||
- Изменённые параметры должны сохраняться в сценарии, не в GUI state.
|
||||
|
||||
## Ограничения
|
||||
|
||||
Время доставки учитывает последовательность hop и очередь на линке, но **не** включает
|
||||
коллизии, hidden terminals, duty cycle, retransmission, FEC, TCP congestion control, радиолокацию,
|
||||
OS scheduling и стоимость crypto. Выбор пути не знает о бэклоге.
|
||||
|
||||
Нельзя из такого графа делать заявления «реальная сеть быстрее Reticulum».
|
||||
34
docs/simulator/scenarios.md
Normal file
34
docs/simulator/scenarios.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
# Сценарии для City Lab и регрессионных тестов
|
||||
|
||||
## S1 · LoRa discovery, Wi-Fi photo
|
||||
|
||||
- A — клиент, B — реле, C — друг.
|
||||
- A–B: SlowRadio, A–C: FastWireless, B–C: SlowRadio.
|
||||
- Text A→C может идти напрямую или через B по метрике.
|
||||
- Photo A→C **только** fast link; при отключении A–C фото QUEUED.
|
||||
|
||||
## S2 · Городские две магистрали
|
||||
|
||||
- 12 узлов: 8 клиентов, 2 relay, 2 backbone.
|
||||
- У каждой магистрали резервное беспроводное ребро.
|
||||
- Bulk идёт по fast сегментам, контрольные объявления лимитируются на slow.
|
||||
|
||||
## S3 · Partition/merge
|
||||
|
||||
- Граф из двух районов, между ними 1 bridge.
|
||||
- После отключения bridge новые сообщения `Queued`, не `Delivered`.
|
||||
- При восстановлении моста очередь переходит к доставке.
|
||||
|
||||
## S4 · Злая нагрузка
|
||||
|
||||
- 100 текстовых сообщений + 1 фото 5 MiB при медленном LoRa.
|
||||
- Проверить, что фото не блокирует канал discovery: `slow_radio_airtime_ms` не содержит фото.
|
||||
- Очередь на slow-линке растёт, часть текстов может истечь по TTL (`tests/capacity/`).
|
||||
- Метрики: control airtime, бэклог линка, p95 поиска. Квоты control пока не реализованы.
|
||||
|
||||
## S5 · Повторяемость
|
||||
|
||||
- Одинаковый начальный граф и последовательность действий → одинаковые результаты и CSV.
|
||||
- Случайных отказов и `seed` пока нет; когда появятся, seed обязан входить в сценарий.
|
||||
|
||||
Не смешивать с реальными RF-измерениями. [Подробнее о метриках](metrics.md).
|
||||
Loading…
Add table
Add a link
Reference in a new issue