MOBAflow

MOBAflow is an event-driven automation solution for model railroads. The system enables complex workflow sequences, train control with station announcements, and real-time feedback monitoring via direct UDP connection to the Roco Z21 Digital Command Station.

⚖️ Legal Notice: MOBAflow is an independent open-source project. See THIRD-PARTY-NOTICES.md for details on third-party software, formats, and trademarks (AnyRail, Piko, Roco).

✨ Features

🚂 Z21 Direct UDP Control – Real-time communication with Roco Z21
🎯 Journey Management – Define train routes with multiple stations
🧭 Flexible Layout – Toggle City and Workflow libraries to maximize workspace
🔊 Text-to-Speech – Azure Cognitive Services & Windows Speech API
⚡ Workflow Automation – Event-driven action sequences
🎨 Visual Track Plan – Drag & drop track editor with snap-to-connect
🟢 Win2D GPU Rendering – High-performance track visualization
🛤️ Track Libraries – Extensible support (Piko A-Gleis, Roco Line, Tillig, Märklin)
📱 Multi-Host – MOBAflow (Windows), MOBAsmart (Android), MOBApi (REST)
🟢 Status Monitoring – Real-time startup progress with log streaming

📚 Need Help? Check out our comprehensive Wiki Documentation

WinUI User Guide – Learn how to use MOBAflow

Azure Speech Setup – Configure text-to-speech

Installation Guide – Set up MOBAflow, MOBApi and MOBAsmart

⚠️ Hardware & Safety

MOBAflow controls model train layouts via UDP communication with the Roco Z21 Digital Command Station.

⚠️ Important Safety Information

Before using MOBAflow, please read: 📖 HARDWARE-DISCLAIMER.md

This document covers:

✅ Safety requirements and prerequisites

✅ Network configuration

✅ Liability & disclaimer

✅ Emergency procedures

Current Status: ℹ️ Azure App Configuration setup scripts are available. Hardware setup, device pairing, and layout integration are still manual.

🚀 Quick Start

Prerequisites

✅ .NET 10 SDK matching global.json
✅ Visual Studio 2026 (recommended) or VS Code
✅ Roco Z21 Digital Command Station (for Z21 connectivity)

Clone & Build

git clone https://github.com/ahuelsmann/MOBAflow.git
cd MOBAflow
dotnet restore MOBAflow/MOBAflow.csproj
dotnet build MOBAflow/MOBAflow.csproj

Cross-platform subset (library and backend projects only):

dotnet restore Backend/Backend.csproj
dotnet build Backend/Backend.csproj
dotnet test Test/Test.csproj

Note: On non-Windows systems, the WinUI and MAUI projects are not buildable. Restore/build individual .csproj files instead of relying on solution-level restore. Some System.Speech tests are Windows-only.

Run Applications

🪟 MOBAflow (Windows Desktop):

dotnet run --project MOBAflow/MOBAflow.csproj

🌐 MOBApi (REST API, Port 5001):

dotnet run --project MOBApi/MOBApi.csproj

MOBApi listens on port 5001 (all interfaces). It provides the REST API for the MOBAflow Overview status and for MOBAsmart (client list, health).

You can start MOBApi in two ways:

Standalone – run the command above.
Together with MOBAflow – enable "Auto-start REST API with MOBAflow" in MOBAflow Settings so MOBAflow starts the MOBApi process automatically.

MOBAsmart discovers the server via UDP multicast; ensure PC and phone are on the same network.

📱 MOBAsmart (Android):

dotnet build MOBAsmart/MOBAsmart.csproj -f net10.0-android

🧪 Run Tests:

dotnet test Test/Test.csproj

🔐 Trust Model & Signatures

Official MOBAflow releases are identified by signed Git tags in this repository.

Release versions are tagged as X.Y.Z (e.g. 0.1.0).
Starting with version 0.1.0, maintainers sign these tags with their GPG keys so you can verify that a given version really comes from us and was not modified.

How to use signed versions as a user

Typical workflow for installing a specific version:

Select a version: Pick a tag from the GitHub Tags / Releases list (e.g. 0.1.0).
Fetch tags & verify:
```
git fetch origin --tags
git tag -v 0.1.0
```
Only continue if GPG reports a valid signature from a maintainer key listed in docs/legal/MAINTAINERS.md.
Check out the tag:
```
git checkout 0.1.0
```
Build & run using the commands from the Quick Start section.

Verifying a Release Tag

git fetch origin --tags
git tag -v 1.2.3

Only trust tags whose signature matches one of the maintainer keys documented in docs/legal/MAINTAINERS.md (e.g. key ID 7DAD81238FEE2F49).
If verification fails, do not use that release and contact the maintainers.

Maintainer Keys

The current list of GPG keys and fingerprints used for signing release tags is maintained in:

docs/legal/MAINTAINERS.md

🔧 Configuration

MOBAflow uses Azure Cognitive Services Speech for text-to-speech announcements. Choose your preferred setup method:

🎯 Setup Options

Method	Best For	Complexity
A) Azure App Config	Teams, shared environments	⭐⭐⭐
B) User Secrets	Individual developers	⭐⭐
C) Settings UI	End users, no coding	⭐

Option A: Azure App Configuration (Teams)

💡 For Developer Teams: Centralized configuration shared across all team members.

Quick Setup:

# 1. Create Azure resource (once)
.\scripts\setup-azure-appconfig.ps1 -SpeechKey "YOUR-KEY" -SpeechRegion "germanywestcentral"

# 2. Install on all team systems
.\scripts\install-appconfig-connection.ps1 -ConnectionString "YOUR-CONNECTION-STRING"

# 3. Restart IDE

📖 Details: See 🔧 Setup Scripts section below

Option B: User Secrets (Developers)

1. Get Azure Speech Key:

🌐 Go to Azure Portal
➕ Create: Cognitive Services → Speech
📋 Copy Key and Region

2. Configure Secrets:

cd MOBAflow
dotnet user-secrets set "Speech:Key" "YOUR-AZURE-SPEECH-KEY"
dotnet user-secrets set "Speech:Region" "germanywestcentral"

3. Verify: Run the app – speech should work ✅

Option C: Settings UI (End Users)

1. Launch MOBAflow
2. Navigate: Settings → Speech Synthesis
3. Enter your Azure Speech Key
4. Select Region (e.g., germanywestcentral)
5. Click Save

⚠️ Security: The key is stored locally in appsettings.json. Never commit this file to version control.

Configuration Priority

The app loads settings in this order (first found wins):

☁️ Azure App Configuration (if AZURE_APPCONFIG_CONNECTION env var exists)
🔐 User Secrets (Development mode only)
⚙️ Settings UI (appsettings.json)
🚫 Fallback: Speech features disabled

🛤️ Track Plan

Design your model railroad layout with MOBAflow's visual track planning system.

✨ Track Plan Features

✅ Drag & Drop – Place tracks from toolbox
✅ Snap-to-Connect – Automatic track joining
✅ Grid Alignment – Rotation & positioning controls
✅ Theming – Light & Dark mode support
✅ Navigation – Zoom & Pan
✅ Feedback Points – Assign detection sensors
✅ Validation – Real-time constraint checking
✅ Signal Control – Requires active Z21 connection
✅ Win2D Rendering – GPU-accelerated graphics (Phase 1)

🛤️ Supported Track Systems

Library	Status	Description
TrackLibrary.PikoA	✅ Active	Piko A-Gleis
TrackLibrary.RocoLine	🚧 Planned	Roco Line
TrackLibrary.Tillig	🚧 Planned	Tillig
TrackLibrary.Maerklin	🚧 Planned	Märklin

🎵 Audio Library

Play sound effects in workflows (station bells, train whistles, crossing signals).

📂 Directory Structure

Sound/Resources/Sounds/
├── Station/          # Station bells, gongs, platform warnings
├── Train/            # Whistles, horns, brake sounds
├── Signals/          # Warning beeps, crossing bells
└── Ambient/          # Background ambience (optional)

📋 Requirements

Property	Value
Format	`.wav` (PCM only)
Sample Rate	44100 Hz or 48000 Hz
Bit Depth	16-bit
Channels	Mono or Stereo
Not Supported	❌ .mp3, .ogg, .flac

🎯 Naming Conventions

✅ Good	❌ Bad
`arrival_bell.wav`	`sound1.wav`
`whistle_short.wav`	`ArrivalBell.wav`
`crossing_warning.wav`	`My Sound.wav`

📥 Adding Sounds

Download from Freesound.org (CC0 license recommended)
Copy to appropriate subfolder
Use in Workflow: Create Audio Action → Set FilePath

⚖️ Licensing

✅ CC0 (Public Domain) – No attribution required
✅ CC-BY 4.0 – Attribution required (add to ATTRIBUTION.md)
❌ CC-BY-NC – Avoid (non-commercial restriction)

📖 Attribution File: Sound/Resources/Sounds/ATTRIBUTION.md

🎨 Control Libraries

Platform-specific UI control libraries for consistent, reusable components.

🏗️ Architecture

MOBAflow/Controls/       ← WinUI 3 XAML controls inside the desktop app
    ↓
MAUI.Controls/           ← MAUI XAML (Android Mobile)
    ↓
SharedUI/                ← ViewModels (Platform-agnostic)
    ↓
Domain/                  ← Business Models

📦 Available Libraries

Project	Platform	Technology	Target
MOBAflow/Controls	Windows	WinUI 3 XAML	Desktop app control set
MAUI.Controls	Android	.NET MAUI XAML	Mobile control library
SharedUI	Cross-platform	CommunityToolkit.Mvvm	ViewModels

🪟 Windows Controls in MOBAflow

<Page xmlns:controls="using:Moba.WinUI.Controls">
    <controls:TrainCard 
        TrainName="ICE 1" 
        Speed="120" 
        IsForward="True" />
</Page>

Guidelines:

Use DependencyProperty for bindable properties
Prefer x:Bind (compiled bindings)
Use ThemeResource for colors/styles
Follow Fluent Design System

📱 MAUI.Controls (Android)

<ContentPage xmlns:controls="clr-namespace:Moba.MAUI.Controls;assembly=MAUI.Controls">
    <controls:TrainCard 
        TrainName="ICE 1" 
        Speed="120" 
        IsForward="True" />
</ContentPage>

Guidelines:

Use BindableProperty for bindable properties
Use AppThemeBinding for Light/Dark mode
Touch-optimized (minimum 44x44 dp)
Follow MAUI design patterns

⚖️ Platform Differences

Feature	MOBAflow/Controls	MAUI.Controls
Bindable Properties	`DependencyProperty`	`BindableProperty`
Binding Syntax	`{x:Bind}`	`{Binding}`
Base Class	`UserControl`	`ContentView`
Icons	`FontIcon`	`FontImageSource`
Theming	`ThemeResource`	`AppThemeBinding`

📦 Architecture

MOBAflow follows Clean Architecture principles with strict layer separation.

🏗️ Layer Structure

┌─────────────────────────────────────┐
│  MOBAflow / MOBAsmart / MOBApi      │  ← Platform UI & API
├─────────────────────────────────────┤
│  SharedUI (ViewModels)              │  ← MVVM Layer
├─────────────────────────────────────┤
│  Backend (Services, Logic)          │  ← Business Logic
├─────────────────────────────────────┤
│  Domain (Models, POCOs)             │  ← Core Entities
└─────────────────────────────────────┘

Runtime Boundary (Current Status)

Shared ViewModels talk to the in-process runtime only; there is no separate UI client interface:

MainWindowViewModel / TrainControlViewModel / MauiViewModel
  ↓
IMobaRuntime  (MobaRuntimeService)
  ↓
IZ21 / JourneyManager / WorkflowService

Current scope:

MainWindowViewModel, TrainControlViewModel, and MauiViewModel inject IMobaRuntime (singleton MobaRuntimeService) instead of using IZ21 or JourneyManager directly for commands and snapshots
The runtime publishes MobaRuntimeSnapshot (and related events such as traffic and feedback) back to the shell
Project activation is performed inside MobaRuntimeService.ActivateProjectAsync, which owns ActiveProjectContext and a JourneyManager per active project
The active runtime still uses the live Project instance from the loaded Solution; a dedicated runtime copy remains a possible future step
Shared master data (data.json) is held in MasterDataStore (Backend DI); WinUI services expose cities and locomotives to the shell

🛠️ Technology Stack

Layer	Technology
Framework	.NET 10
UI	WinUI 3 (MOBAflow), .NET MAUI (MOBAsmart)
API	ASP.NET Core REST + SignalR (MOBApi)
Graphics	Microsoft.Graphics.Win2D
MVVM	CommunityToolkit.Mvvm
Logging	Serilog (File + In-Memory Sink)
Speech	Azure Cognitive Services, Windows Speech
Networking	Direct UDP (Z21 Protocol)
Testing	NUnit

📄 Solution File Format

MOBAflow uses System.Text.Json with schema validation.

Schema Version

{
  "name": "My Model Railroad",
  "schemaVersion": 1,
  "projects": [...]
}

Current Schema Version: 1

Validation Rules

✅ JSON Structure – Valid syntax
✅ Required Properties – name, projects
✅ Schema Version – Compatibility check
✅ Project Integrity – Valid structure

📊 Logging Infrastructure

Serilog Configuration:

📁 File Logs: bin/Debug/logs/mobaflow-YYYYMMDD.log (rolling, 7-day retention)
💾 In-Memory Sink: Real-time log streaming to MonitorPage UI
🔍 Structured Logging: Searchable properties
📊 Log Levels: Debug (Moba), Warning (Microsoft)

Example:

_logger.LogInformation(
    "Feedback received: InPort={InPort}, Value={Value}",
    inPort,
    value);

📖 Details: See docs/ARCHITECTURE.md

🔧 Setup Scripts (For Teams)

💡 For Developer Teams: Centralized Azure App Configuration for shared environments.

👤 For End Users: Skip this section and use Settings UI instead.

📜 Available Scripts

Script	Purpose	Run Where
`setup-azure-appconfig.ps1`	Create resource	Once (any system)
`install-appconfig-connection.ps1`	Set env var	All systems

🚀 Quick Team Setup

1. Create Azure Resource:

.\scripts\setup-azure-appconfig.ps1 `
    -SpeechKey "YOUR-KEY" `
    -SpeechRegion "germanywestcentral"

Output: Copy the Connection String ✅

2. Install on Team Systems:

.\scripts\install-appconfig-connection.ps1 `
    -ConnectionString "Endpoint=https://...;Id=...;Secret=..."

3. Restart IDE:

Close and reopen Visual Studio / VS Code

4. Verify:

Speech settings automatically load from Azure – no local config needed! ✅

📖 Script Details

setup-azure-appconfig.ps1

Purpose: Creates Azure App Configuration resource

Parameters:

-SpeechKey (required) – Azure Speech API Key
-SpeechRegion (required) – Azure region (e.g., germanywestcentral)
-ResourceGroupName (optional) – Default: MOBAflow-RG
-ConfigStoreName (optional) – Default: mobaflow-config
-Location (optional) – Default: germanywestcentral

Requirements:

Azure CLI installed
Logged in (az login)
Subscription selected (az account set)

install-appconfig-connection.ps1

Purpose: Sets AZURE_APPCONFIG_CONNECTION environment variable