# `esp-hal` Roadmap

## Projects

### Improve and expand the public APIs of peripheral drivers

- Some peripheral drivers have sub-optimal APIs
- There are often usability issues with the APIs
- This can be due to generics/complex types (see below), or just poor API design
- It may be worth doing a bit of a top-down redesign of some drivers
- Many peripheral drivers do not expose all available functionality
- We should identify instances of this and open issues where possible
- Not all functionality may be particularly useful, so we should prioritize this
- Reduce typestates/generic params where possible
- They can be useful but imo having 5+ generic params on something makes for a hellish experience
- We can likely type erase a number of driver structs once initialization has completed
- We should identify instances of this and open issues as able

### Configuration

- There is currently no way to configure options such as ~~stack size~~, flash size, etc.
- Other than flash size, are there any other properties to configure?

### Usability/UX

- The prelude in its current form does not really work for the `embedded-hal-*@1.0.0-rc.1` traits
- This is non-trivial to solve, and I'm not sure there's a perfect solution

### Reduce dependence on `embedded-hal`

- Drivers should be operable without importing the `embedded-hal` traits via the driver's public API
- One example of this is the watchdogs; I can't imagine there is a sensor driver out there that requires a watchdog, so we shouldn't need to rely on these traits in order to configure the peripheral

### The `soc` module

- We need to finish what we started, and try to refactor whatever else we can into this module
- I think we need to have a discussion about what belongs here and what doesn't
- The `soc::constants` module either needs to have items removed, or items added, once we define its scope

---

## Jesse's Brain Dump

- Hardware-in-loop testing is becoming increasingly important
- I have started working on this, and have a general plan; however, we're currently blocked on a `probe-rs` issue. Once this is resolved I can continue work.
- The plan is to use [teleprobe](https://github.com/embassy-rs/teleprobe/tree/main/teleprobe), which is the application used in `embassy` for HIL testing. I have had to modify this project to get it working with our devices (disregarding the aforementioned issue) and will upstream these changes when able.
- This application is reasonably battle-tested already, so I'm comfortable relying on it
- We will probably start with just some very primitive tests, and expand on these over time
- One thing to decide on: when should these tests run? Do we want to run HIL tests on every PR, have scheduled runs, other?
- Peripheral drivers need to be updated so that they are usable __without__ any `embedded-hal-*` traits. We should not be reliant on these traits to simple **USE** the HAL; traits are analogous to interfaces, they provide only an API for interoperability.
- There are a number of APIs which probably need to be redesigned. Some of these include:
- GPIO
- There are a number of open issues for this peripheral
- The types and APIs are probably not ideal
- This is a fundamental peripheral driver, and having a good API benefits the rest of the code base
- We are still missing some functionality here (eg. inverted GPIO)
- ADC
- There are a number of open issues for this peripheral
- I think the API can probably be simplified
- DMA
- I don't see any need to differentiate between `Gdma` and `Pdma` for the driver struct names; this only adds complications (eg. interoperability)
- **TODO:** Identify other peripheral drivers which need API improvements
- If there is serious interest from the IDF Core Team in having some common low-level HAL in Rust, then we need to fundamentally rething our architecture and possibly spin out a few more packages than we already have
- We need pretty strict and complete requirements to make this a possibility, I think. There are a lot of moving parts here and lots to consider.
- Examples are increasingly becoming a maintenance burden
- I am working on an example generator which should hopefully help with this, but it will take some time to complete
- I currently have converted between 1/4 and 1/3 of examples to templates
- Not sure that this is an ideal solution, but can't think of an alternative. We already have ~400 examples and this number is only going to increase, so we need to do something.
- I think we can probably eliminate some examples, and can consolidate some others to cut down own the total a bit, as well
- We should pick a board for each chip and double check that all the pins we're using make sense, just for consistency
- There are some peripherals which still need their names unified (eg. `RTC_CNTL`/`LP_CLKRST`), so identify and resolve these