Generic firmware/family support

[ankitgoswami]

Context

ePIC firmware runs on Antminer hardware and gets fully discovered by asic-rs (the underlying Rust library, v0.5.0): it returns firmware="ePIC" and make="AntMiner" for ePIC-on-Antminer, and make="ePIC", firmware="ePIC" for native ePIC hardware. But the proto-fleet asicrs plugin rejects it because of a chain of hardcoded enums/tables in plugin/asicrs/src/capabilities.rs:

• A constant per family (FAMILY_*) and per variant (VARIANT_*)
• A make_to_family() table that requires every aftermarket firmware name to be listed
• A firmware_to_variant() substring matcher with a fixed set of arms
• A firmware_manufacturer() map from variant key → display name
• A config.yaml that explicitly lists every family/variant under an opt-in enabled: true flag

Every time asic-rs adds a new firmware (e.g., ePIC) or a new make, proto-fleet has to add five+ constants, three+ table entries, and a config block. That's the rigidity to fix.

The asic-rs library already gives us clean canonical strings via the MinerFirmware and MinerMake Display impls — we should use them as the keys and stop maintaining a parallel taxonomy. Once we do, ePIC support drops out for free.

Design

Principle: asic-rs's make and firmware Display strings are the source of truth. The plugin layer normalizes them (lowercase, alphanumeric only) into config keys and uses them directly. New firmwares/makes from asic-rs flow through automatically. Specialization (credentials, auth strategies) stays explicit but degrades gracefully to sensible defaults so new entries work without code.

What changes

1. Replace identification constants with a normalize function in plugin/asicrs/src/capabilities.rs:

   /// Normalize an asic-rs make/firmware Display string into a config key:
   /// lowercase, alphanumeric only. Examples:
   ///   "AntMiner"     -> "antminer"
   ///   "ePIC"         -> "epic"
   ///   "WhatsMiner"   -> "whatsminer"
   ///   "MARAFW_1.0.0" -> "marafw10"  (handled below)
   pub fn normalize_key(s: &str) -> String {
       s.chars()
           .filter(|c| c.is_ascii_alphanumeric())
           .map(|c| c.to_ascii_lowercase())
           .collect()
   }

2. Replace make_to_family / firmware_to_variant / detect_variant with two thin wrappers that operate on the asic-rs Display strings:

   pub fn family_key(make: &str) -> String { normalize_key(make) }
   
   pub fn variant_key(firmware: &str) -> String {
       // Strip trailing version digits/underscores so "MARAFW_1.0.0" -> "marafw"
       let alpha: String = firmware
           .chars()
           .take_while(|c| c.is_ascii_alphabetic())
           .map(|c| c.to_ascii_lowercase())
           .collect();
       if alpha.is_empty() { "stock".into() } else { alpha }
   }

   • Drops all the substring matching and fallback chains.
   • "VNish" → "vnish", "Braiins" → "braiins", "LuxOS" → "luxos", "MaraFW" → "marafw" (new key — see migration below), "ePIC" → "epic", "" → "stock".
   • The make-fallback in detect_variant is no longer needed because asic-rs always populates device_info.firmware via the MinerFirmware Display impl. (Confirmed: see asic-rs-firmwares/epic/src/firmware.rs L66-70 and the corresponding impls for vnish/marathon/etc.) The signature-based caller in plugin/asicrs/src/device.rs:773-774 (VNish hostname strategy) only needs variant_key("VNish") == "vnish", which works.

3. Drop firmware_manufacturer() entirely. The display name is already in device_info.firmware (canonical asic-rs Display string like "ePIC"). In driver.rs:354-356 and driver.rs:513-515, replace:

   let manufacturer = firmware_manufacturer(variant)
       .unwrap_or(make.as_str())
       .to_string();

   with:

   // Stock firmware: show the hardware make. Aftermarket: show the firmware vendor.
   let manufacturer = if variant == "stock" { make.clone() } else { firmware_str.clone() };

   This means VNish devices will show "VNish" (whatever asic-rs returns) — no parallel DISPLAY_* table to keep in sync.

4. Default-allow config in plugin/asicrs/src/config.rs:

   • Add a default_enabled: bool field to PluginSettings (defaults to true).
   • is_firmware_enabled(family, variant) returns the explicit enabled value if a miners.<family>.<variant> entry exists, otherwise default_enabled.

   pub fn is_firmware_enabled(&self, family: &str, variant: &str) -> bool {
       self.miners
           .get(family)
           .and_then(|f| f.firmware.get(variant))
           .map(|fw| fw.enabled)
           .unwrap_or(self.plugin.default_enabled)
   }

   • Drop the self.config.miners.contains_key(family) early-reject in driver.rs:293-296 — is_firmware_enabled now handles unknown families cleanly.

5. Shrink config.yaml to just the explicit overrides:

   plugin:
     log_level: info
     discovery_timeout_seconds: 10
     telemetry_cache_ttl_seconds: 5
     default_enabled: true   # any asic-rs-supported miner is allowed by default
   
   miners:
     # Disable stock Antminer here so the Go antminer plugin owns it.
     antminer:
       stock:
         enabled: false

   New asic-rs miners/firmwares (ePIC today, the next one tomorrow) need zero config.

6. canonical_port(family) in driver.rs:74-83 — keep the explicit map for known families but fall back to 80 for unknown families (HTTP web is the most common asic-rs default). Update the match to a small static table with a default arm. Replace crate::capabilities::FAMILY_* references with string literals ("whatsminer", etc.).

7. default_credentials(family, variant) in capabilities.rs:326-356 — restructure so credentials are keyed by variant first (firmware vendor sets the auth, not the hardware), with family as fallback for stock:

   pub fn default_credentials(family: &str, variant: &str) -> Vec<DefaultCredential> {
       // Aftermarket firmware: vendor-specific defaults.
       match variant {
           "vnish" => return vec![cred("admin", "admin")],
           "epic"  => return vec![cred("admin", "letmein")],
           "braiins" | "luxos" | "marathon" | "marafw" => {} // fall through to family default
           _ => {}
       }
       // Stock / unknown: family-keyed defaults.
       match family {
           "whatsminer"  => vec![cred("admin", "admin"), cred("super", "super")],
           "antminer"    => vec![cred("root", "root")],
           "avalonminer" => vec![cred("admin", "admin")],
           "epic"        => vec![cred("admin", "letmein")],
           _             => vec![cred("admin", "admin")],   // generic fallback
       }
   }

   • ePIC firmware on any hardware → admin/letmein (one line)
   • New firmware variants without a credential entry → fall through to family default → ultimately to admin/admin if family is also unknown
   • Caller can still override via the access field

8. Update plugin/asicrs/src/device.rs:773-774 to use the new function:

   match crate::capabilities::variant_key(firmware).as_str() {
       "vnish" => Self::Hostname,
       _       => Self::Default,
   }

   No change to existing behavior; just the call site.

9. Defensive Go-plugin update in plugin/antminer/internal/driver/driver.go:42-52:

   • Add firmwareMarkerEpic = "epic" and append to nonStockFirmwareMarkers.
   • ePIC firmware speaks HTTP on 4028, not CGMiner, so the Go plugin's GetVersion() should fail to handshake anyway — but the marker is documentation for the next reader and a safety net.
   • Note: this list still requires a manual entry per firmware, since we can't query asic-rs from the Go side. Acceptable cost — it's defensive only.

What stays the same

• verify_identity, normalize_mac, capability probing (probe_capabilities, static_base_capabilities, driver_base_capabilities) — already dynamic via the asic-rs Miner trait.
• DefaultCredential struct.
• The MinerFamilyConfig schema (miners.<family>.<variant>.enabled) — only the resolution logic changes.

Migration / behavioral deltas to be aware of

• Variant key for Marathon: today firmware_to_variant("MARAFW_1.0.0") returns "marathon" via an explicit alias. With the new scheme, variant_key("MaraFW") (the asic-rs Display string) returns "marafw", not "marathon". Two options:
  • (a) Accept the rename — config and credentials use marafw. Cleaner, no aliases.
  • (b) Keep one alias map for legacy names: {"marafw": "marathon"}. Less surprise for existing config files but reintroduces the table.
  • Recommend (a) since config.yaml is shrinking to almost nothing and marafw matches asic-rs's Display.
• Manufacturer display string: today's DISPLAY_VNISH = "VNish" etc. matches asic-rs's Display anyway, so swapping to "use whatever asic-rs returns" should be a no-op for existing variants. Verify via the existing antminer-vnish contract test.
• Native ePIC: with default_enabled: true, native ePIC hardware (family=epic, variant=epic) auto-enables. No explicit config needed. The existing epic.stock block in config.yaml:35-37 becomes obsolete and can be deleted.