Fully automated customization of EmComm Tools Community (ETC) ISO images using xorriso/squashfs. No GUI required.
Upstream Project: EmComm Tools Community
Documentation: community.emcommtools.com
ETC already includes all ham radio tools (Winlink, VARA, JS8Call, fldigi, etc.). This customizer adds:
- β Pre-configured WiFi networks (auto-connect on boot)
- β
Personal callsign and grid square (pre-populated for
et-user) - β
Hostname set to
ETC-{CALLSIGN} - β Desktop preferences (dark mode, scaling, accessibility)
- β Display & screen management (brightness, dimming, blank timeout)
- β Power management (sleep behavior, power profiles, idle actions)
- β System timezone configuration
- β Additional development packages (VS Code, Node.js, npm, git)
- β VARA license pre-registration (manual registry edit β backup β auto-restore on builds)
- β VS Code workspace setup (standard project location included in et-user-backup)
- β
Automatic user config restoration (from
etc-user-backup-*.tar.gzif present) - β APRS configuration (iGate, beacon, digipeater with smart beaconing)
- β Ham radio CAT control (Anytone D578UV with DigiRig Mobile, rigctld auto-start)
- β
Optional et-os-addons features (individually configurable):
- VR-N76 radio config, GridTracker, WSJT-X Improved, QSSTV, XYGrib, Kiwix, JS8Spotter, NetControl, WiFi hotspot, user backup tool
- Control via
ENABLE_ETOSADDONS_*variables insecrets.env(all enabled by default)
- β Git configuration
- β
Embedded cache files for faster rebuilds (use
-mfor minimal)
This customizer respects upstream ETC architecture. We:
- Keep ETC's runtime template system (et-direwolf, et-yaac, etc.)
- Modify templates in-place, keeping
{{ET_*}}placeholders - Don't change package selections or install additional software
- Don't pre-install VARA or Wine prefix (these require a desktop session post-install)
- Build process: Fully automated ETC ISO customization via xorriso/squashfs
- WiFi configuration: Networks are pre-configured in NetworkManager
- User config restoration: Automatic backup extraction (etc-user-backup-*.tar.gz)
- User settings restored during ISO build
- Wine prefix auto-restored on first login post-install
- 300-second timeout prevents build hangs
- Progress tracking for large backups
- APRS configuration: Full direwolf template customization
- iGate mode (internet gateway) with APRS-IS login
- Smart beaconing with configurable interval
- Digipeater WIDE path support
- Separate from Packet/Winlink (no conflicts)
- Ham radio CAT control: Anytone D578UV with DigiRig Mobile
- Rigctld daemon auto-starts at boot (localhost:4532)
- Active radio config automatically created
- udev rules for /dev/et-cat symlink (CP2102/CH340/PL2303/FTDI)
- Users can select different radio via
et-radioafter boot
- D578 CAT Control: DigiRig Mobile configuration for CAT control (et-mode packet/Winlink compatible)
- User config:
~/.config/emcomm-tools/user.jsonpre-populated with callsign, grid, Winlink password - Desktop settings: Dark mode, scaling, accessibility, display, power management, timezone all applied
- Git config: User name/email configured
- VARA license setup: Pre-register via Wine registry, create backup, auto-restore on builds
- VS Code workspace: Pre-configured workspace with Projects directory in ~/.config/emcomm-tools/
- Additional packages: Development tools (VS Code, git, nodejs, npm, CHIRP via pipx) installable via configuration
- Cache system: Downloaded ISOs cached for faster rebuilds
- Preseed automation: Ubuntu 22.10 installer fully automated with debian-installer (d-i)
- No interactive prompts: keyboard, locale, hostname, username, password, timezone, partitioning all preseed-driven
- Text-based installer (d-i) respects all preseed directives including partitioning
- Anytone D578UV radio: Radio configuration added to et-radio menu (rigctrl ID 301)
The et-os-addons repository provides optional application launchers and configurations. These are enabled by default but can be disabled via ENABLE_ETOSADDONS_* variables in secrets.env:
| Feature | Variable | Description |
|---|---|---|
| VR-N76 Radio | ENABLE_ETOSADDONS_VR_N76 |
VR-N76 old radio utility and preset config |
| QSSTV | ENABLE_ETOSADDONS_QSSTV |
QSSTV slow-scan TV launcher and config template |
| WSJT-X | ENABLE_ETOSADDONS_WSJTX |
WSJT-X launcher and config template |
| JS8 Spotter | ENABLE_ETOSADDONS_JS8SPOTTER |
JS8Call spotting utility and launcher |
| NetControl | ENABLE_ETOSADDONS_NETCONTROL |
Network control utility with launcher |
| WiFi Hotspot | ENABLE_ETOSADDONS_HOTSPOT |
WiFi hotspot launcher utility |
| User Backup | ENABLE_ETOSADDONS_USERBACKUP |
User backup/restore manager utility |
| Kiwix | ENABLE_ETOSADDONS_KIWIX |
Offline content browser with desktop integration |
| VGC VR-N76 Radio | Always enabled | VGC VR-N76 radio config for et-radio menu |
To disable a feature, set the variable to "no" in secrets.env:
ENABLE_ETOSADDONS_QSSTV="no" # Disable QSSTV
ENABLE_ETOSADDONS_WSJTX="no" # Disable WSJT-XAll features default to "yes" and are integrated explicitly into the build process with no overwrites.
The ISO uses debian-installer (d-i) with preseed for zero-interaction installation. All setup questions are answered automatically from your configuration.
Automated Installation Workflow:
- Boot custom ISO from Ventoy
- GRUB menu shows all available OSes (dual-boot preserved)
- Select Ubuntu/EmComm Tools entry from menu
- GRUB loads preseed from
preseed/file=/cdrom/preseed.cfg - Preseed parameters:
auto=true priority=critical(enable automatic mode) - Debian-installer runs WITHOUT user prompts for:
- Keyboard layout
- Locale / language
- Hostname (set to
ETC-{CALLSIGN}) - Username (set from config)
- Password (hashed in preseed)
- Timezone
- Partitioning (strategy-aware, respects dual-boot)
- Package selection (ubuntu-desktop task)
- System boots directly to desktop (or login prompt if autologin disabled)
- All customizations apply automatically (WiFi, APRS, desktop settings, CAT control, etc.)
Why debian-installer instead of ubiquity?
The original approach used Ubuntu's ubiquity (GUI installer) with automatic-ubiquity boot parameter. However:
- β Ubiquity ignores partitioning directives in preseed - asks user anyway
- β Ubiquity ignores many d-i settings (not designed for full automation)
- β Ubiquity can't skip accessibility/release notes questions
- β Debian-installer respects ALL preseed directives including full partitioning
- β D-i is text-based - faster, no GUI overhead
The debian-installer is the standard Debian/Ubuntu preseed solution and provides true "set it and forget it" automation.
Preseed File & Boot Parameters:
The GRUB configuration is automatically updated to:
linux /casper/vmlinuz preseed/file=/cdrom/preseed.cfg auto=true priority=critical maybe-ubiquity quiet splash ---This tells debian-installer to:
- Load preseed answers from
preseed/file=/cdrom/preseed.cfg auto=true- enable automatic mode (defer some early questions to allow preseed loading)priority=critical- only ask questions marked critical; skip all othersmaybe-ubiquity- still attempts GUI installer if available, falls back to text d-i
Partitioning Behavior:
The preseed adapts based on INSTALL_DISK and PARTITION_STRATEGY configuration:
-
Partition Mode (
PARTITION_STRATEGY="force-partition",INSTALL_DISK="/dev/sda5"):- Uses
d-i partman-auto/method string regular(non-destructive) - Debian-installer targets specified partition only
- Safe for dual-boot systems
- Respects existing Windows/other OS partitions
- Uses
-
Auto-Detect Mode (
PARTITION_STRATEGY="auto-detect",INSTALL_DISK="") β Default, Recommended:- Script analyzes disk layout before building ISO
- Automatically chooses safest strategy (usually partition mode)
- Embedded in preseed so installer knows partitioning approach
- Prevents destructive mistakes on multi-partition systems
-
Entire-Disk Mode (
PARTITION_STRATEGY="force-entire-disk",CONFIRM_ENTIRE_DISK="yes"):- Uses
d-i partman-auto/method string lvm(auto-partition with LVM) - DESTRUCTIVE: Erases entire disk and creates new partitions
- Requires explicit confirmation in
secrets.env - Only use for single-disk systems with no existing data
- Uses
Reference: Debian Preseed Documentation
Remaining planned features for future releases:
- #3 - WiFi network connection validation and troubleshooting
- #2 - Post-install script for first-boot customizations
View all work: GitHub Issues
Build logs are automatically created and embedded in the ISO for post-install diagnostics:
On the build machine (after running build script):
# View the latest build log
less logs/build-etc-iso_YYYYMMDD_HHMMSS.log
# View all build logs
ls logs/On the installed system:
# Logs are embedded in the ISO and available at:
/opt/emcomm-customizer-cache/logs/
# Copy to home directory for easy access:
mkdir -p ~/.emcomm-customizer/logs
cp /opt/emcomm-customizer-cache/logs/* ~/.emcomm-customizer/logs/
# View the build manifest (summary of what was customized)
less ~/.emcomm-customizer/logs/BUILD_MANIFEST.txtThe build manifest includes:
- Build date and ETC version
- Configuration snapshot (callsign, hostname, WiFi networks, APRS settings)
- Number of successful customization steps
- List of all operations performed
Use the logs to debug issues like WiFi configuration, APRS settings, or any failed customizations.
emcomm-tools-customizer/
βββ build-etc-iso.sh # Main build script (fully automated)
βββ secrets.env.template # Configuration template
βββ secrets.env # Your configuration (gitignored)
βββ cache/ # Downloaded files (persistent)
β βββ ubuntu-22.10-desktop-amd64.iso # β Drop your ISO here!
βββ output/ # Generated custom ISOs
βββ logs/ # Build logs
βββ post-install/ # Scripts for after ISO installation
Ubuntu 22.10 reached end-of-life, so you must first update apt sources:
# Fix apt sources for EOL Ubuntu 22.10
sudo sed -i 's/archive.ubuntu.com/old-releases.ubuntu.com/g' /etc/apt/sources.list
sudo sed -i 's/security.ubuntu.com/old-releases.ubuntu.com/g' /etc/apt/sources.list
sudo apt update
# Install build dependencies
sudo apt install -y xorriso squashfs-tools wget curl jq# Clone repository
git clone https://github.com/AlwaysLearningTech/emcomm-tools-customizer.git
cd emcomm-tools-customizer
# Create configuration
cp secrets.env.template secrets.env
nano secrets.env # Fill in your values
# Build from stable release (downloads ETC + Ubuntu ISO automatically)
sudo ./build-etc-iso.sh -r stable
# Output: output/<release-tag>-custom.isoTo avoid downloading the 3.6GB Ubuntu ISO each time:
# Create cache directory and copy your ISO there
mkdir -p cache
cp ~/Downloads/ubuntu-22.10-desktop-amd64.iso cache/
# Now build - ISO download will be skipped!
sudo ./build-etc-iso.sh -r stableThe script checks cache/ubuntu-22.10-desktop-amd64.iso before downloading.
# List available releases and tags from GitHub
./build-etc-iso.sh -l
# Build from stable release (recommended for most users)
sudo ./build-etc-iso.sh -r stable
# Build from latest development tag (bleeding edge)
sudo ./build-etc-iso.sh -r latest
# Build a specific tag by name
sudo ./build-etc-iso.sh -r tag -t emcomm-tools-os-community-20251113-r5-build17
# Minimal build (smaller ISO, no embedded cache files)
sudo ./build-etc-iso.sh -r stable -m
# Debug mode (show detailed DEBUG log messages)
sudo ./build-etc-iso.sh -r stable -d
# Verbose mode for maximum debugging (bash -x)
sudo ./build-etc-iso.sh -r stable -v| Option | Description |
|---|---|
-r <stable|latest|tag> |
Release mode |
-t <tag> |
Specific tag name (required with -r tag) |
-l |
List available releases and tags |
-m |
Minimal build (exclude cache files, saves ~4GB) |
-d |
Debug mode (show DEBUG log messages) |
-v |
Verbose mode (bash -x tracing) |
-h |
Show help |
Note: Optional et-os-addons features are enabled by default via ENABLE_ETOSADDONS_* variables. Disable individual features by setting them to "no" in secrets.env.
| Mode | Description | Source |
|---|---|---|
stable |
Latest GitHub Release (production-ready) | Releases |
latest |
Most recent git tag (development) | Tags |
tag |
Specific tag by name | Use with -t |
By default, cache files (Ubuntu ISO, ETC tarballs) are embedded in /opt/emcomm-customizer-cache/
so they're available for the next build on the installed system. This is useful when building
on the same machine you install to.
Use -m for a minimal build that excludes these files (saves ~4GB).
Optional features from et-os-addons are integrated into every build. Control individual features via ENABLE_ETOSADDONS_* variables in secrets.env.
What's Available:
- GridTracker 2 - Real-time FT8/FT4 propagation and CQ spotting
- WSJT-X Improved - FT8/FT4 with optimized settings
- QSSTV - Slow-scan TV transmission and reception
- XYGrib - Weather routing and GRIB file downloads
- Kiwix - Offline Wikipedia and documentation archives
- JS8Call Spotter - JS8Call network spotting integration
- NetControl - Network control and monitoring utility
- WiFi Hotspot - Quick WiFi AP sharing from command line
- User Backup/Restore - Backup and restore ETC user settings
- VR-N76 Radio Config - Support for VGC VR-N76 radio (always included)
Configuration:
Features default to enabled. To disable specific features, edit secrets.env:
ENABLE_ETOSADDONS_WSJTX="yes" # Keep WSJT-X
ENABLE_ETOSADDONS_GRIDTRACKER="yes" # Keep GridTracker
ENABLE_ETOSADDONS_QSSTV="no" # Exclude QSSTV
ENABLE_ETOSADDONS_KIWIX="no" # Exclude offline Wikipedia
ENABLE_ETOSADDONS_NETCONTROL="no" # Exclude NetControlDisabled features won't be installed, saving build time and ISO size. See the Optional et-os-addons Features table above for all available variables and descriptions.
Note: et-os-addons features require the source in cache/et-os-addons-main/. Clone it with:
git clone https://github.com/clifjones/et-os-addons.git cache/et-os-addons-mainIf not present, the build continues normally with features disabled.
# === User Identity (REQUIRED) ===
CALLSIGN="N0CALL" # Your amateur radio callsign
USER_FULLNAME="Your Name" # Full name for git commits
USER_EMAIL="you@example.com" # Email for git commits
GRID_SQUARE="CN87" # Maidenhead grid locator
# === User Account ===
USER_USERNAME="" # Linux username (defaults to lowercase CALLSIGN)
USER_PASSWORD="" # Password (leave blank to keep ETC default)
ENABLE_AUTOLOGIN="no" # "yes" or "no" - default is NO (password prompt)
# === System ===
MACHINE_NAME="" # Hostname (defaults to ETC-{CALLSIGN})
TIMEZONE="America/Denver" # System timezone (Linux format, see /usr/share/zoneinfo/)
# === Desktop Preferences ===
DESKTOP_COLOR_SCHEME="prefer-dark" # prefer-dark or prefer-light
DESKTOP_SCALING_FACTOR="1.0" # 1.0, 1.25, 1.5, or 2.0
DISABLE_ACCESSIBILITY="yes" # yes = disable screen reader, on-screen keyboard
# === Display & Screen Management ===
AUTOMATIC_SCREEN_BRIGHTNESS="false" # true = adaptive brightness, false = manual
DIM_SCREEN="true" # true = dim screen during idle
SCREEN_BLANK="true" # true = blank screen after idle timeout
SCREEN_BLANK_TIMEOUT="300" # Seconds before screen blanks (300=5min)
# === Power Management ===
POWER_MODE="balanced" # balanced, performance, or power-saver
POWER_LID_CLOSE_AC="suspend" # AC lid close: nothing, suspend, hibernate, logout
POWER_LID_CLOSE_BATTERY="suspend" # Battery lid close: nothing, suspend, hibernate, logout
POWER_BUTTON_ACTION="interactive" # Power button: nothing, suspend, hibernate, interactive
POWER_IDLE_AC="nothing" # AC idle action: nothing, suspend, hibernate
POWER_IDLE_BATTERY="suspend" # Battery idle action: nothing, suspend, hibernate
POWER_IDLE_TIMEOUT="900" # Seconds before idle action (900=15min)
AUTOMATIC_POWER_SAVER="true" # true = enable power saver on battery
AUTOMATIC_SUSPEND="true" # true = enable automatic suspend
# === Additional System Packages ===
ADDITIONAL_PACKAGES="code git nodejs npm" # Space-separated apt packages to install
# === WiFi Networks ===
WIFI_SSID_HOME="YourHomeNetwork"
WIFI_PASSWORD_HOME="YourHomePassword"
WIFI_AUTOCONNECT_HOME="yes"
WIFI_SSID_MOBILE="YourHotspot"
WIFI_PASSWORD_MOBILE="HotspotPassword"
WIFI_AUTOCONNECT_MOBILE="yes"
# === Winlink ===
WINLINK_PASSWORD="" # Your Winlink password
# === APRS Configuration ===
APRS_SSID="10" # SSID (0-15, 10=iGate)
APRS_PASSCODE="-1" # APRS-IS passcode (-1=RX only)
APRS_SYMBOL="/r" # Symbol: table+code (/r=antenna)
APRS_COMMENT="EmComm iGate" # Beacon comment
# APRS Beacon (position beaconing)
ENABLE_APRS_BEACON="no" # Enable position beaconing
APRS_BEACON_INTERVAL="300" # Seconds between beacons
APRS_BEACON_VIA="WIDE1-1" # Digipeater path
APRS_BEACON_POWER="10" # PHG: Power in watts
APRS_BEACON_HEIGHT="20" # PHG: Antenna height (feet)
APRS_BEACON_GAIN="3" # PHG: Antenna gain (dBi)
# APRS iGate (RF to Internet gateway)
ENABLE_APRS_IGATE="yes" # Enable iGate
APRS_SERVER="noam.aprs2.net" # APRS-IS server
# Direwolf Audio
DIREWOLF_ADEVICE="plughw:1,0" # Audio device (Digirig)
DIREWOLF_PTT="CM108" # PTT method
# === VARA License (Optional) ===
VARA_FM_CALLSIGN="" # Callsign registered with VARA FM license
VARA_FM_LICENSE_KEY="" # Your VARA FM license key
VARA_HF_CALLSIGN="" # Callsign registered with VARA HF license
VARA_HF_LICENSE_KEY="" # Your VARA HF license key
# === Pat Winlink Aliases ===
PAT_EMCOMM_ALIAS="yes" # Create "emcomm" quick-connect alias
PAT_EMCOMM_GATEWAY="" # Gateway callsign (e.g., "W7ACS-10")
# === Power Management ===
POWER_LID_CLOSE_AC="suspend" # Lid close on AC power
POWER_LID_CLOSE_BATTERY="suspend" # Lid close on battery
POWER_BUTTON_ACTION="interactive" # Power button action
POWER_IDLE_AC="nothing" # Idle action on AC
POWER_IDLE_BATTERY="suspend" # Idle action on battery
POWER_IDLE_TIMEOUT="900" # Idle timeout (seconds)The build script automatically detects your disk layout and chooses the safest partitioning strategy. This feature was redesigned to handle three common scenarios:
Partition Strategy Options:
# === AUTO-DETECT (Default - Recommended) ===
# Script analyzes disk layout and chooses the best strategy automatically
PARTITION_STRATEGY="auto-detect" # Analyze and decide
INSTALL_DISK="" # Leave empty (auto-detect) or specify disk
CONFIRM_ENTIRE_DISK="no" # No confirmation needed for auto-detect
# === FORCE PARTITION MODE (Dual-Boot) ===
# Use existing partition - safe for dual-boot systems
PARTITION_STRATEGY="force-partition"
INSTALL_DISK="/dev/sda5" # Target partition (ends with digit)
CONFIRM_ENTIRE_DISK="no"
# === FORCE ENTIRE-DISK MODE (Dedicated System) ===
# WARNING: DESTRUCTIVE - erases entire disk and creates new partitions with LVM
# Only use for fresh installs with no data on the target disk
PARTITION_STRATEGY="force-entire-disk"
INSTALL_DISK="/dev/sda" # Entire disk (no partition number)
CONFIRM_ENTIRE_DISK="yes" # MUST be "yes" to proceed
# === FORCE FREE-SPACE MODE (Windows Dual-Boot with Space) ===
# Create partitions in available free space on Windows partition
PARTITION_STRATEGY="force-free-space"
INSTALL_DISK="/dev/sda" # Disk with Windows partition + free space
CONFIRM_ENTIRE_DISK="no" # No confirmation neededHow Auto-Detect Works:
When PARTITION_STRATEGY="auto-detect" (default), the script:
-
Checks if
INSTALL_DISKis a specific partition (e.g.,/dev/sda5):- β Uses partition mode (safe for dual-boot)
-
If disk is blank or only has Linux partitions:
- β Uses entire-disk mode (LVM auto-partitioning)
-
If Windows partition detected with free space:
- β Uses free-space mode (create partitions in gap)
-
If Windows partition detected with NO free space:
- β Requires CONFIRM_ENTIRE_DISK="yes" to proceed with entire-disk
Strategy Behavior Comparison:
| Strategy | INSTALL_DISK | Behavior | Preseed Config | Best For |
|---|---|---|---|---|
| auto-detect | empty or disk | Analyze and decide | Dynamic based on disk | Most users |
| partition | /dev/sda5 |
Use manual partitioning for single partition | partman-auto/method regular |
Dual-boot (Windows+ETC) |
| entire-disk | /dev/sda |
Auto-partition entire disk with LVM | partman-auto/method lvm |
Fresh install, single disk |
| free-space | /dev/sda |
Create partitions in available free space | partman-auto/method regular + free space |
Windows with 50GB+ free |
Preseed Partitioning Details:
-
Partition Mode (
partman-auto/method string regular):- Uses standard ext4 filesystem (no LVM)
- Requires you to have pre-partitioned the disk
- Safe for dual-boot: only modifies target partition
- Swap configured at next partition number (e.g., sda6 if using sda5)
-
Entire-Disk Mode (
partman-auto/method string lvm):- DESTRUCTIVE: Erases all partitions on target disk
- Uses LVM for flexible partition management
- Automatic partition sizing with swap
- Only use if you're certain about target disk
-
Free-Space Mode (
partman-auto/method string regular):- Creates new partitions in unallocated space
- Preserves Windows partition
- Ideal for upgrading Windows system to dual-boot
Size Calculation:
The script calculates optimal partition sizes:
Available Space = Total Disk Size
Swap Size = MIN(25% of available, MAX(2GB, MIN(4GB)))
EXT4 Size = Remaining space
Override calculated sizes (optional):
SWAP_SIZE_MB="4096" # Force 4GB swap (in MB)
EXT4_SIZE_MB="51200" # Force 50GB ext4 (in MB)Safety Features:
- β Partition mode is always safe (targets one partition only)
- β
Entire-disk mode requires
CONFIRM_ENTIRE_DISK="yes"to proceed - β Auto-detect chooses safest option based on current disk layout
- β Script validates partition paths before generating preseed
- β Detailed logging shows detected strategy and proposed partitioning
VARA is commercial software with two separate products:
| Product | Cost | Use Case |
|---|---|---|
| VARA FM | ~$69 | VHF/UHF Winlink via FM repeaters |
| VARA HF | ~$69 | HF Winlink for long-distance |
Purchase at rosmodem.wordpress.com
How License Registration Works
When you run the VARA installers, they write registration keys to the Wine registry. Rather than trying to script this during ISO build (where Wine doesn't exist yet), we use a manual registration β backup β restore workflow:
Step 1: Manual Registry Editing (One-Time)
Before creating a Wine backup:
- Install VARA:
cd ~/add-ons/wine && ./01-install-wine-deps.sh && ./02-install-vara-hf.sh && ./03-install-vara-fm.sh - Open Wine registry editor with direct key access:
export WINEPREFIX="$HOME/.wine32" wine regedit
- Navigate to
HKEY_CURRENT_USER β Software β VARA FMand add/edit:Callsign(string): Your callsignLicense(string): Your license key
- Navigate to
HKEY_CURRENT_USER β Software β VARAand add/edit (for VARA HF):Callsign(string): Your callsignLicense(string): Your license key
- Close regedit
Step 2: Create Wine Backup
tar -czf ~/etc-wine-backup-with-vara.tar.gz ~/.wine32/
cp ~/etc-wine-backup-with-vara.tar.gz /path/to/emcomm-tools-customizer/cache/Step 3: Automatic Restoration on Future Builds
Place the backup in cache/ before building. The build script automatically restores it:
- Wine prefix is extracted on first login (deferred from build to avoid hangs)
- VARA registration keys are immediately available
- VARA runs with licenses on first launch
Why This Approach?
- β Registry edits are handled correctly by Windows/Wine GUI tools
- β
Avoids fragile
.regfile scripting - β Wine prefix persists across ISO builds via backup
- β Licenses pre-loaded on every new system
- β Works with ETC's upstream warning: "Don't backup before applications run" (we backup AFTER proper Wine initialization)
Pat is the Winlink client on ETC. The emcomm alias adds a quick-connect shortcut to your standard Pat config:
pat connect emcomm # Quick connect to your configured gatewayAfter first boot, run ~/.config/pat/add-emcomm-alias.sh to add the alias to your Pat config.
A pre-configured VS Code workspace is created at ~/.config/emcomm-tools/emcomm-tools.code-workspace:
Features:
- Projects directory:
~/.config/emcomm-tools/Projects/- standard location for all repos and development - Workspace file: Open in VS Code via
File β Open Workspace from Fileorcode ~/.config/emcomm-tools/emcomm-tools.code-workspace - Automatic backup: All files in Projects are included in et-user-backup
- Recommended extensions: Python, Pylance, C++, Prettier, GitLens, Remote Explorer
Using the workspace:
-
Clone repos or create projects in
~/.config/emcomm-tools/Projects/cd ~/.config/emcomm-tools/Projects git clone https://github.com/user/repo.git
-
Backup your projects for next rebuild:
tar -czf ~/etc-user-backup-$(date +%Y%m%d).tar.gz ~/.config/ cp ~/etc-user-backup-*.tar.gz /path/to/emcomm-tools-customizer/cache/
-
Next ISO build automatically restores your workspace and projects on first login
Project organization suggestion:
Projects/
βββ ham-radio/ # Ham radio related projects
βββ emcomm/ # EmComm Tools customizations
βββ scripts/ # Utility scripts
βββ personal/ # Personal projects
The build automatically installs:
- VS Code - editor
- Node.js & npm - JavaScript development
- git - version control
- CHIRP - Radio programming software (via pipx)
Additional packages can be configured in secrets.env via ADDITIONAL_PACKAGES variable.
FULLY AUTOMATED DURING BUILD β
If you place backup files in the cache/ directory before building, they are automatically restored during ISO customization with proper timeout handling:
-
cache/etc-user-backup-*.tar.gzβ User configs extracted to ISO immediately (~30-60 seconds)- Includes:
~/.config/emcomm-tools,~/.local/share, documents, desktop settings - Extracted directly into
/etc/skelduring build (applied to new users)
- Includes:
-
cache/etc-wine-backup-*.tar.gzβ Wine prefix auto-restored on first login (deferred from build)- VARA registry and prefix data available immediately after first login
- Deferred to avoid hanging during ISO build (Wine prefix extraction is slow)
Automation Details:
-
User backup: Uses
timeout 300 tar xzf ... --checkpoint=.1000 --checkpoint-action=dot- 300-second timeout prevents hangs on large backups (611MB+)
- Progress tracking shows extraction status (every 1000 files = one dot)
- Extracted during build (fast, doesn't block other customizations)
-
Wine backup: Copied to
~/.etc-backups/during build~/.etc-backups/00-restore-wine-backup.shauto-runs on first login- Restores Wine prefix to
~/.wine32from backup tarball - Runs asynchronously (doesn't block desktop startup)
How to Use:
- Create backups from existing ETC installation:
# On existing ETC system:
et-user-backup # Creates cache/etc-user-backup-*.tar.gz
# If you also want Wine/VARA settings:
et-user-backup --wine # Includes .wine32 (creates ~600MB backup)
# Copy to your build machine's cache/
scp user@etc-machine:cache/etc-*-backup*.tar.gz ./cache/- Run build - backups are extracted automatically:
./build-etc-iso.sh -r stable
# User backup: extracts during build (watch for progress dots)
# Wine backup: copied to ~/.etc-backups/, restores on first login- Boot the ISO - all user settings + Wine/VARA auto-restored
What Gets Restored:
From user backup:
~/.config/emcomm-tools/- ETC configuration (callsign, grid, user.json)~/.local/share/emcomm-tools/- Maps, tilesets, application data~/.local/share/pat/- Winlink Pat settings (mailbox passwords, aliases)~/.local/share/WSJT-X/- WSJT-X settings and logs~/Documents/- Your documents folder~/.navit/- Navigation bookmarks and maps~/my-maps/- Custom map data~/YAAC/- YAAC configuration
From Wine backup (optional):
~/.wine32/- Entire Wine 32-bit prefix (VARA HF/FM with installed licenses)
Technical Details:
- User backup extraction: Uses tar with
--checkpointfor progress tracking - Timeout: 300 seconds (5 minutes) - if extraction takes longer, partial restore is used
- Wine backup: Large file (500MB+) is NOT extracted during ISO build; instead it's copied to
~/.etc-backups/and restored automatically on first user login - No blocking: Wine extraction deferred to first login avoids "hanging" during ISO build
Alternative: Manual Restoration (if backups not in cache/)
If you didn't place backups in the cache/ directory before building, you can restore manually after the OS boots:
# Copy backup to home directory
cp /path/to/etc-user-backup-*.tar.gz ~
# Restore user configuration only
tar xzf ~/etc-user-backup-*.tar.gz -C ~/
# Or restore with Wine prefix
tar xzf ~/etc-user-backup-*.tar.gz -C ~/ # user config
tar xzf ~/etc-wine-backup-*.tar.gz -C ~/ # Wine prefixAUTOMATIC DIREWOLF TEMPLATE MODIFICATION β
APRS configuration is automatically applied during ISO build by modifying ETC's direwolf template. This is completely separate from Packet/Winlink mode (no conflicts).
Features:
- iGate Mode - Upload position/weather to APRS-IS internet server (requires login)
- Smart Beaconing - Automatic position updates based on movement/time
- Digipeater Support - WIDE path relaying for packet radio network
- ETC Template System - Respects ETC's
{{ET_*}}runtime placeholders
Configuration Variables:
# === APRS Configuration ===
APRS_SSID="10" # Station SSID (10=iGate, 11-15 for specific roles)
APRS_PASSCODE="" # APRS-IS passcode (-1 for RX only)
APRS_SYMBOL="r/" # Two-character symbol: r/=portable, a/=digipeater, etc.
APRS_COMMENT="EmComm Tools - ETC" # Station comment/info string
ENABLE_APRS_IGATE="yes" # yes/no - enable APRS-IS internet gateway
ENABLE_APRS_BEACON="yes" # yes/no - enable position beaconing
APRS_SERVER="noam.aprs2.net" # APRS-IS server (noam=N.America, euro=Europe, etc.)
APRS_BEACON_INTERVAL="30" # Beacon interval in minutes (smart beaconing)
APRS_BEACON_DISTANCE="1" # Distance in miles before beacon (movement trigger)
DIREWOLF_ADEVICE="plughw:1,0" # Audio device for direwolf
DIREWOLF_PTT="CM108" # PTT method: CM108 (USB audio) or GPIOHow It Works:
During ISO build, the script:
- Modifies direwolf template at
/opt/emcomm-tools/conf/template.d/packet/direwolf.aprs-digipeater.conf - Populates user.json with callsign, grid square, Winlink password
- Adds IGSERVER/IGLOGIN settings when
ENABLE_APRS_IGATE=yes - Adds PBEACON/SMARTBEACONING when
ENABLE_APRS_BEACON=yes - Adds DIGIPEAT configuration for WIDE path support
Template Preservation:
All template modifications preserve ETC's {{ET_*}} placeholders. This means:
- Users can still override settings at runtime via
et-mode - Selecting different mode (e.g., switching to Packet) doesn't break configuration
- Updates to ETC templates don't conflict with our customizations
Symbol Codes:
Common APRS symbols (first character / second character):
Primary/Overlay:
a/ = APRS/Beacon, b/ = Buoy, c/ = Cloud, d/ = Digipeater
e/ = Eyeball, f/ = Fire, g/ = Glider, h/ = Hospital
i/ = Interstate, j/ = Jeep, k/ = Kenwood, l/ = Lighthouse
m/ = Mobile, n/ = Node, o/ = OVEN, p/ = Police
q/ = Query, r/ = RV, s/ = Shuttle, t/ = Truck
u/ = User, v/ = Van, w/ = Water, x/ = X-APRS
y/ = Yagi, z/ = Zero
r/ = Portable = most common for field stations
a/ = Digipeater = recommended for relay stations
Server Choices:
noam.aprs2.net = North America (default)
euro.aprs2.net = Europe
asia.aprs2.net = Asia
aunz.aprs2.net = Australia/New Zealand
Post-Install Testing:
After building and booting:
# Start direwolf in APRS mode
et-mode aprs
# Watch direwolf logs
tail -f ~/.etc-cache/direwolf.log
# Verify APRS-IS gateway connection (watch for "Connected to")
journalctl -u direwolf -f| Setting | Options | Description |
|---|---|---|
| Lid Close | nothing, suspend, hibernate, logout |
What happens when laptop lid closes |
| Power Button | interactive, suspend, hibernate, poweroff |
Power button behavior |
| Idle Action | nothing, suspend, hibernate |
Action after idle timeout |
| Idle Timeout | Seconds (e.g., 900 = 15 min) |
Time before idle action triggers |
These variables control ETC's optional features and map downloads during the ISO build.
Interactive vs Automated Builds:
- Variables configured β Downloads happen automatically, no prompts
- Variables blank β Original ETC dialog prompts appear during build
- This ensures future ETC versions with new dialogs still work interactively
| Variable | Options | Description |
|---|---|---|
OSM_MAP_STATE |
US state name (lowercase) | OpenStreetMap data for offline Navit navigation |
ET_MAP_REGION |
us, ca, world |
Pre-rendered raster tiles for YAAC and other apps |
ET_EXPERT |
yes or blank |
Enables Wikipedia download (ETC internal variable) |
WIKIPEDIA_SECTIONS |
Comma-separated list | Offline Wikipedia sections (requires ET_EXPERT=yes) |
Note about ET_EXPERT: This is an undocumented ETC variable. When set, it:
- Enables the Wikipedia download dialog during install
- Shows a Wine info textbox during wine installation
Leave blank unless you want Wikipedia offline content.
OSM State Names: Use lowercase state names from Geofabrik US:
alabama, alaska, arizona, arkansas, california, colorado, connecticut, delaware, district-of-columbia, florida, georgia, hawaii, idaho, illinois, indiana, iowa, kansas, kentucky, louisiana, maine, maryland, massachusetts, michigan, minnesota, mississippi, missouri, montana, nebraska, nevada, new-hampshire, new-jersey, new-mexico, new-york, north-carolina, north-dakota, ohio, oklahoma, oregon, pennsylvania, rhode-island, south-carolina, south-dakota, tennessee, texas, utah, vermont, virginia, washington, west-virginia, wisconsin, wyoming
ET Map Regions:
| Region | File Size | Coverage |
|---|---|---|
us |
~2.5 GB | United States, zoom 0-11 |
ca |
~1.5 GB | Canada, zoom 0-10 |
world |
~500 MB | Global, zoom 0-7 |
Wikipedia Sections: Available sections for offline Wikipedia:
computer, history, mathematics, medicine, simple
Examples:
# Fully automated build (no Wikipedia)
OSM_MAP_STATE="washington"
ET_MAP_REGION="us"
ET_EXPERT=""
WIKIPEDIA_SECTIONS=""
# Fully automated with Wikipedia
OSM_MAP_STATE="washington"
ET_MAP_REGION="us"
ET_EXPERT="yes"
WIKIPEDIA_SECTIONS="computer,medicine"
# Semi-automated - let dialog prompt for maps you're unsure about
OSM_MAP_STATE="" # Will show dialog to pick state
ET_MAP_REGION="us" # Auto-download US tilesThere are two ways to get offline Wikipedia content on ETC:
Set ET_EXPERT="yes" and WIKIPEDIA_SECTIONS="computer,medicine" to download pre-built .zim files from Kiwix during the build. These are large files (100-500MB each) covering entire topic areas.
This customizer includes a script to create a small, targeted .zim file with just the Wikipedia articles relevant to ham radio operators.
Configuration:
# In secrets.env - specify individual articles (pipe-separated)
WIKIPEDIA_ARTICLES="2-meter_band|70-centimeter_band|General_Mobile_Radio_Service|Family_Radio_Service"Default articles include:
- Band information: 2-meter band, 70-centimeter band, HF/VHF/UHF
- Radio services: GMRS, FRS, MURS, Citizens Band
- Digital modes: APRS, Winlink, DMR, D-STAR, System Fusion
- Emergency comms: Amateur radio emergency communications
- General ham radio topics: Repeaters, simplex, antennas, propagation
Post-Install Usage: After first boot, run the Wikipedia ZIM creator:
cd ~/add-ons/wikipedia
./create-my-wikipedia.shThis downloads your configured articles and creates a .zim file in ~/wikipedia/ that you can view with Kiwix:
# Start local server
kiwix-serve --port=8080 ~/wikipedia/ham-radio-wikipedia_*.zim
# Open http://localhost:8080 in browserNote: The custom .zim creator is a post-install script because it requires network access and takes a few minutes to run. It's NOT embedded in the ISO build.
| SSID | Usage |
|---|---|
| 0 | Primary station (home, fixed) |
| 1 | Digipeater, fill-in digi |
| 2 | Digipeater (alternate) |
| 3 | Portable station |
| 4 | HF to VHF gateway |
| 5 | Smartphone, mobile app |
| 6 | Satellite ops, special |
| 7 | Handheld, walkie-talkie |
| 8 | Boat, maritime mobile |
| 9 | Mobile (car, truck, RV) |
| 10 | Internet, APRS-IS only |
| 11 | Balloon, aircraft, spacecraft |
| 12 | APRStt, DTMF, touchstone |
| 13 | Weather station |
| 14 | Trucking |
| 15 | Generic, other |
Symbols are specified with a two-character code: table + symbol.
Primary Table Symbols (table = /)
| Symbol Code | Icon | Description |
|---|---|---|
/> |
π | Car |
/y |
π | House with antenna |
/[ |
πΆ | Jogger/Walker (portable) |
/_ |
π€οΈ | Weather station |
/! |
π | Police station |
/# |
π | Digipeater |
/$ |
π | Phone |
/- |
π | House (QTH) |
/. |
β | X / Unknown |
// |
π΄ | Red Dot |
/? |
β | Question mark |
/K |
π« | School |
/R |
π½οΈ | Restaurant |
/Y |
β΅ | Yacht/Sailboat |
/^ |
Large aircraft | |
/a |
π | Ambulance |
/b |
π² | Bicycle |
/f |
π | Fire truck |
/k |
π | Truck |
/n |
π‘ | Node (packet) |
/r |
π» | Antenna/Portable |
/s |
π’ | Ship (power) |
/u |
π | Bus |
/v |
π | Van |
Alternate Table Symbols (table = \)
| Symbol Code | Icon | Description |
|---|---|---|
\> |
π | Car (overlay capable) |
\a |
πͺ | ARES/RACES |
\# |
π | Digipeater (overlay) |
\& |
π· | Diamond (overlay) |
\- |
π | House (HF) |
\0 |
β | Circle (numbered) |
\K |
π | Helicopter |
\^ |
Small aircraft | |
\j |
ποΈ | Camping |
\k |
ποΈ | ATV/Motorcycle |
\n |
πΊ | Triangle (overlay) |
\s |
π₯οΈ | Small boat |
\v |
πΊ | ATV (overlay) |
Full table: APRS Symbol Codes
The cache/ directory stores downloaded files to speed up rebuilds:
cache/
βββ ubuntu-22.10-desktop-amd64.iso # Ubuntu base ISO (3.6 GB)
βββ emcomm-tools-os-*.tar.gz # ETC installer tarballs
To skip downloads:
- Create
cache/directory - Copy
ubuntu-22.10-desktop-amd64.isointo it - Run build - download will be skipped
ETC tarballs are also cached automatically after first download.
Generated ISOs are placed in output/:
output/
βββ emcomm-tools-os-community-20251128-r5-final-5.0.0-custom.iso
Copy to Ventoy USB:
cp output/*.iso /media/$USER/Ventoy/
syncSymptom: The built ISO boots into a standard Ubuntu installer asking you to create a user, with none of the ETC tools installed.
Cause: The ETC installer (install.sh) failed silently during the chroot phase.
Fixes (as of v1.1.0):
- Build now verifies the ETC tarball extraction was successful
- Build now verifies ETC installation by checking for
/opt/emcomm-toolsandet-user - Build now properly captures the chroot exit code
If you still encounter this, run with -d flag for debug output and check the log file in logs/.
Symptom: After installing the ISO on a dual-boot system (especially Panasonic Toughbook FZ-G1), screen brightness controls no longer work in either Windows or Ubuntu.
Causes: The Intel graphics backlight controller can get confused by ACPI/UEFI state changes during OS installation.
Fixes:
-
Try BIOS reset: Power off completely, enter BIOS setup, and load "Setup Defaults" then save and exit.
-
Windows Device Manager: Device Manager β Display Adapters β Intel HD Graphics β Update/Rollback Driver
-
Ubuntu kernel parameters: Edit
/etc/default/grub, find theGRUB_CMDLINE_LINUX_DEFAULTline and add one of:acpi_backlight=vendor acpi_backlight=video acpi_backlight=nativeThen run
sudo update-gruband reboot. -
Intel xbacklight: Install
xbacklightand use it directly:sudo apt install xbacklight xbacklight -set 50 # Set to 50% -
Direct sysfs control (last resort):
# Find the backlight device ls /sys/class/backlight/ # Typically intel_backlight or acpi_video0 # Read max brightness cat /sys/class/backlight/intel_backlight/max_brightness # Set brightness (example: 500) echo 500 | sudo tee /sys/class/backlight/intel_backlight/brightness
Run with sudo:
sudo ./build-etc-iso.sh -r stableInstall prerequisites (after fixing apt sources for Ubuntu 22.10):
sudo apt install -y xorriso squashfs-tools wget curl jqPre-download and cache:
mkdir -p cache
wget -O cache/ubuntu-22.10-desktop-amd64.iso \
https://old-releases.ubuntu.com/releases/kinetic/ubuntu-22.10-desktop-amd64.iso- Ensure you have 15+ GB free disk space
- The squashfs step takes 10-20 minutes on typical hardware
Several community projects build on ETC. Here's how they relate to this customizer:
- Author: CowboyPilot | Status: Active (v1.2)
- How It Works: Clones to
~/NozzleMods/, addsnozzle-menuinteractive launcher - Real Value: Hardware-specific CAT control configuration that's not in upstream
- AIOC (All-In-One-Cable): Three DireWolf profiles (Simple TNC, Packet Digipeater, APRS Digipeater)
- Yaesu FT-710: Full CAT support with udev rules and device symlinks (
/dev/et-cat,/dev/et-audio) - Xiegu G90: DigiRig PTT configuration (CAT vs RTS modes)
- System tools: Fix APT sources, VarAC V13 .NET fixes
- About VARA: NozzleMods does NOT provide VARA (upstream ETC R5 already has
~/add-ons/wine/scripts for VARA HF/FM). NozzleMods wraps them in a menu and adds port management. - Installation:
curl -fsSL https://raw.githubusercontent.com/CowboyPilot/ETC5_NozzleMods/main/install.sh | bash - Integration Path: Post-install onlyβrequires running system with X11/GNOME for menu. Can't pre-stage in ISO.
- URL: https://github.com/CowboyPilot/ETC5_NozzleMods
- Author: clifjones | Status: Active
- How It Works: Two methods:
- Build-time: Replace ETC tarball URL with et-os-addons during ISO creation
- Post-install: Clone and run on existing ETC system
- What It Adds (via overlay pattern):
- WSJT-X Improved (FT8/FT4/MSK144) - NOT in upstream ETC
- GridTracker 2 - Mapping integration
- JS8Spotter - Spot tracking
- QSSTV + Cheese - SSTV/webcam support
- xygrib + Saildocs - Weather maps
- et-launcher - Rust UI wrapper to reduce CLI usage
- Enhanced et-user-backup - Custom backup directories
- Integration Path: Could integrate into this customizer by:
- Adding
-aor--addonsflag to include their overlay during build - OR: document as alternative build path for users wanting FT8
- Adding
- Licensing Note: Requires building your own ISO (no pre-built images distributed)
- URL: https://github.com/clifjones/et-os-addons
- Author: kf0che
- Status: Maintained but specific to MAGNET organization
- How It Works: Full variant with ETC submodule + custom overlay scripts
- Value: Reference example for building org-specific ETC builds
- Integration Path: Documentation onlyβtoo specialized for general customizer
- URL: https://github.com/kf0che/ETC-MAG
- Author: ekakela
- Platform: Windows (Python-based)
- What It Does: Monitors folder β prints to thermal receipt printer β archives messages
- Best For: Emergency exercises where operators need physical message distribution
- Integration Path: None (different platform, different purpose). Link in docs for interested users.
- URL: https://github.com/ekakela/emcomm-print
Approach: Document + provide post-install hook
Why Separate: Requires running X11 environment with Wine. Must happen after system boots.
Action Items:
- Create
/post-install-hooks/nozzlemods-template.shfor users to customize and run - Document that if you have AIOC/FT-710/G90, run this post-install
- Link directly to NozzleMods GitHub
Approach: Document as alternative build OR optional enhancement flag
Why Separate: Different overlay pattern. Could be integrated but adds ~2GB to ISO.
Decision:
- Option A (Simpler): Keep emcomm-tools-customizer as "base ETC customizer"
Users who want FT8 use et-os-addons instead - Option B (More Work): Add
-aflag to include their overlay at build time
Would require cloning their repo during build, extracting overlay, merging pattern
Approach: Link in README for users with thermal printer workflows
Integration: Noneβdifferent platform
Scenario 1: Basic ETC with custom WiFi/callsign
β Use emcomm-tools-customizer
β Boot, install ISO
β Done (or run et-vara-hf/et-vara-fm from add-ons if you want VARA)
Scenario 2: ETC + AIOC or FT-710 radio
β Use emcomm-tools-customizer
β Boot, install ISO
β Run NozzleMods: curl https://raw... | bash
β nozzle-menu β R) Radio Configuration β select your radio
Scenario 3: ETC + FT8/GridTracker
β Use et-os-addons instead of emcomm-tools-customizer
β Follow et-os-addons build instructions (replaces ETC tarball)
β ISO will have WSJT-X Improved, GridTracker 2
Scenario 4: ETC + everything (custom config + AIOC + FT8)
β Use et-os-addons for FT8/GridTracker
β Document custom build steps for WiFi/callsign (outside upstream)
β After install: Run NozzleMods for AIOC CAT config
- Download: Fetches Ubuntu 22.10 ISO and ETC installer tarball (cached in
cache/) - Extract: Uses xorriso to extract ISO, unsquashfs for filesystem
- Install ETC: Runs ETC's install.sh in chroot to install all ham radio tools
- Verify: Confirms ETC installed correctly by checking for key files
- Customize: Modifies
/etc/skel/and system configs with your settings - Rebuild: Creates new squashfs and ISO with xorriso
All customizations go into /etc/skel/ so they apply to new users automatically.
MIT License - See LICENSE file
- EmComm Tools Community: thetechprepper
- Customizer: KD7DGF
73 de KD7DGF π»