Add a --flash <device> command

[rrbutani]

what

We want to make it possible to flash boards from the TUI.

#6 details a utp-<dev name>-device-info crate that has information about a particular device. We can extend this to also have board specific flashing implementations.

Ultimately we'd want something like:

struct SerialDeviceInfo {
  board_path: ...,
  baud_rate: u32,
}

trait SerialDevice: UtpDevice {
  /// Called if the user does not specify a baud rate explicitly.
  fn baud_rate(&mut self, board_path: &...) -> Option<u32>;

  /// Device autodetection.
  ///
  /// Currently must report 0 or 1 devices; we have no mechanism
  /// for users to pick between multiple.
  fn find_device(&mut self) -> Result<SerialDeviceInfo, Self::Error>;
  // for our TM4C impl we'd want to: check for permissions problems and tell users (Linux) if they should go install the udev rule
}

#[derive(Debug, Error)]
enum FlashError<Other: Error> {
  DeviceNotFound(String),
  Other(#[from] Other)
}

trait FlashableDevice: UtpDevice {
  async fn flash_binary(&mut self, binary: &[u8]) -> Result<(), FlashError<Self::Error>>;
  // for our TM4C impl, maybe find a way to warn users they need to install the ICDI driver?
  //
  // can grab `lm4flash` binaries if `lm4flash` is not in the path, etc.
}

// not sure what the representation for this is going to look like...
//
// label to label mappings (i.e. PF4 = G0) are good and fine
//
// but we also probably want a way to let this impl draw it in
// the TUI?
struct DevicePinout {

}

trait Pinout {
  // not sure if we want this to have access to the device or not;
  // do we want to disallow dynamic pinouts?
  //
  // a compelling reason to would be that that'd let us offer
  // a way to embed the pinout in rustdoc... but we can just
  // have an image URL and that'd be fine too.
  fn get_pinout(&self, /* board_path: &... */) -> DevicePinout;
  // at the least we can use ^ to annotate the ports in the TUI (i.e. `G0 (PF4)`)

  fn pinout_image_url(&self) -> &'static str {
    // not an associated const bc of object safety
  }
}

trait UtpDevice {
  const NAME: &'static str;
  const VERSION: Version; // can have the TUI check the field from RPC and see if there are updates I guess... (TODO)
  const GITHUB_REPO_OWNER: &'static str;
  const GITHUB_REPO_NAME: &'static str;

  type Error: Error;

  fn init() -> Self;

  // the extension trait pattern
  // if `Some`, the `--device NAME` flag is allowed
  fn serial_device(&mut self) -> Option<&mut dyn SerialDevice> { None }

  // if `Some`, the `--flash NAME` flag is allowed
  fn flashable_device(&mut self) -> Option<&mut dyn FlashableDevice> { None }

  fn get_pinout(&self) -> Option<&dyn Pinout> { None }
}

trait UtpDeviceExt: UtpDevice {
  async fn get_binary_release() -> Result<File, ()> {
    // auto impled; grabs from GitHub releases using UtpDevice::GITHUB_REPO_OWNER, GITHUB_REPO_NAME, and VERSION
    ...
  }
}
impl<U: UtpDevice> UtpDeviceExt for U { }

we should have a utp/devices repo
the above should live in a utp-device-info crate in that repo
along with a macro and some helpers to ease implementation
should expose the single trait implementer at crate::DeviceInfo

we should have a utp/device-template repo
that depends on ^
exposes crate::DeviceInfo (i.e. utp-tm4c-device-info::DeviceInfo)
should have CI:

• release workflow that matches the conventions utp-device-info expects
• docs upload (idea is to have the pinout, etc. in the docs)
  should also have a crate for the board, etc.

utp-devices repo in utp/devices that depends on all the device impls we currently have
the docs for this crate (we'll do #[docs(inline)] should have a helpful listing of all the crates
rexport as the device name, have install/setup instructions, etc.

the tui should ultimately depend on ^

steps

• [[ steps ]]

where

branch:

open questions