Ship a 1.0 release

[thejpster]

Part of rust-embedded/wg#383

Settled blockers:

• WIP: Re-organising repo #169 (closed for later consideration)
• [RFC] Changing the way we handle addition/changes to the traits #163
• [RFC] Use core language async primitives instead external crates #172
• [RFC] digital::v3 interface + moving to a single interface
• Use nb 1.0 #234
• Consider improving watchdog API using move semantics #98 PR: Improve watchdog API design using move semantics #222
• PwmPin: allow get_duty to return the old value for some time #140
• Support 7-bit and 10-bit I2C addressing #147 PR: Make I2C compatible with multiple address sizes #230
• Change reference implementation to something more maintained #156
• ADC API does not allow non-unit channels #110
• Creating abstractions over Pwm trait is not ideal #244 PR: Swap PWM channel argument to pass by reference #246
• Turn traits and execution model modules inside out #298
• Capture trait requires moving/copying channel argument #249
• [RFC] Revamp Error types #229 PR: Add error traits for communication interfaces #296
• Pwm enable and disable methods only work for channels #182 PR: Add methods to enable/disable the entire timer #183
• spi: add Read and separate-buffers Transfer #287
• u8 as default SPI Word #321
• SPI: split into device/bus, allows sharing buses with automatic CS #351
• spi: allow impls returning early, add flush.  #365
• Alternative SPI word lengths: add default SPI word types #320
• IoPin trait not practical to implement with multiple input/output types #340
• Extract SPI exclusive device into shared crate #398
• It's not clear when can::ErrorKind::Acknowledge should be returned #387
• Split nb and can traits to separate crates. #394
• WIP: I2C bus/device. #392
• delay: make infallible. #432
• I2c: simplify, expand docs, document shared bus usage. #440
• spi: make SpiDevice transaction take an operation slice instead of a closure. #443
• bus/i2c: add RefCell, CriticalSection and Mutex shared bus implementations. #445
• I2C transaction_iter should take an iterator of mutable references #367
• SPI implementation doesn't follow embedded-hal requirements for CS linux-embedded-hal#87 discussed in WG meetings, we decided we're OK with the solutions in SPI implementation doesn't follow embedded-hal requirements for CS linux-embedded-hal#87 (comment)
• serial: add ReadExact, ReadUntilIdle #349
• New embedded-io release #480
• Migration page #283 PR: Add initial version of migration guide #284
• Update changelogs #482
• Document defmt feature #483
• spi: add settings to embedded-hal-bus SpiDevice impls for CS-to-clock delays. #539 docs in spi: document Operation::DelayNs is not for CS delays. #559, will add CS delays to embedded-hal-bus later.
• RFC: rename DelayNs to Delay #541
• Document SemVer hazards of spi::Operation::DelayNs #552
• Clarify flushing/"blocking" behavior #455

Open blockers:

• gpio: require &mut self in InputPin and StatefulOutputPin. #547
• Revert "gpio: require &mut self in InputPin and StatefulOutputPin" #553 ?
• Release v1.0.0 #555
• Show that MCU and linux implementations work fine
• Show that drivers can work fine with the new changes
• Your issue here!

Feel free to nominate issues also by commenting below

[jamesmunns]

Here is a link to the video call discussion had by myself and most of the members of @rust-embedded/hal team. This includes initial decisions made, and justification/reasoning for each point. The next steps for this would be to codify this into an RFC, and get approval for it (though there is already general consensus within the embedded-hal team).

by the way, this was the "issue with the list of big topics" we were looking for during the meeting :)

[eldruin]

I believe the only unresolved issue as of the list above is #172
I would also add the dependency on rust-embedded/nb#20
Then we need to think about the dev-dependencies which are at the moment stm32f3 and futures. I guess specially these will hold us back for a while.

[Disasm]

This async story began just recently and I do not expect it to end in the coming year. Why should we block on it? We can always add this later. In the worst case, these async traits will be released in embedded-hal v2.0.0.

[therealprof]

I also think we should keep async separate because it's a different paradigm and might need require a different approach anyway. I can imagine taking an approach similar to async-std vs std, i.e. have the async traits in a separate crate async-embedded-hal which would allow crates to move indepedently and express more clearly what is supported where.

[ryankurte]

i have mixed feelings about async being separate in the long term, but imo it very much depends whether we can find an approach (as is the case for one of the demonstrated ones) that allows everything to be a default impl on top of our base nb or poll traits as we have now with the blocking default methods, so we have one source of truth for integration, simplify the job of hal implementers, and you'll always have access to both. Or if these introduce fundamentally incompatible requirements and must be managed separately. this, however, is not something we can conclusively tell afaik.

i posed here (#172 (comment)) that if we have a path towards a decision on the nb/futures swap I would be okay to hold, but so long as it's an open / unknown problem I would also prefer to keep moving and accept integrating async may be another breaking change down the line.

(i would also very much like to hear the thoughts of @japaric if ya have a moment to look at all of this)

[hannobraun]

I'd like to nominate #249 as a blocker for the 1.0 release.

[hannobraun]

@rust-embedded/hal Would you consider releasing 1.0-alpha.2? I'm working on a driver that I'd like to release soon, and it would be great if I had access to PinState.

[eldruin]

Those mean porting a variety of drivers and MCU and linux HAL implementations to the -rc.1 version and reporting if there are any problems or not.
That is where I see help needed the most, since it is based on community work.

[pbert519]

What exactly means a variety of drivers and HAL implementations?
Is it a number? A percentage? A list of important crates? A feeling?
The goal is not measurable unless there is some kind of definition.

[Finomnis]

I would in general be interested in starting a migration for imxrt-hal. The important open question to me is: How stable is the embedded-hal 1.0 API already? How much can we expect it to change? Is it intended to stay as-is and only change if we discover problems? Or are there still open design decisions?

[Dirbaio]

1.0-rc1 should be identical to the final 1.0, unless some problem is discovered.

[tgross35]

Is there a target release date? I think crates are probably more likely to start a port in seriousness (and discover bugs) if there is a solid plan to release before the end of the year, barring anything fatal. After all, some crates have had open issues for switching to 1.0 for three years atsamd-rs/atsamd#332

[tgross35]

esp-hal already supports this rc esp-rs/esp-hal#926

[ithinuel]

https://github.com/rp-rs/rp-hal does too :)

[tgross35]

Just searching around https://grep.app/search?q=embedded-hal%5Cw%2A%20%3D.%2A1%5C.0.%2A%28rc%7Calpha%29&regexp=true, it seems like it is actually pretty well used already.

• linux-embedded-hal https://github.com/rust-embedded/linux-embedded-hal
• Everything Embassy https://github.com/embassy-rs/embassy (Dirbaio is a maintainer of both)
• Raspberry Pi silicon HAL https://github.com/rp-rs/rp-hal (thanks @ithinuel)
• The Raspberry Pi PAL https://github.com/golemparts/rppal
• EspressIf Switch to embedded-hal version 1.0 esp-rs/esp-hal#926
• A mock library for the HAL https://github.com/dbrgn/embedded-hal-mock
• W5500 ethernet over SPI driver https://github.com/newAM/w5500-rs
• An epaper driver https://github.com/caemor/epd-waveshare
• Flipper SDK https://github.com/flipperzero-rs/flipperzero
• Drogue IoT https://github.com/drogue-iot/drogue-device
• BME280 I2C sensor driver https://github.com/VersBinarii/bme280-rs
• BME680 sensor driver https://github.com/marcelbuesing/bme680
• BL602 HAL https://github.com/sipeed/bl602-hal
• Generic GPIO/SPI/I2C display interface driver https://github.com/therealprof/display-interface
• RTIC https://github.com/rtic-rs/rtic
• U-Blox cell driver https://github.com/BlackbirdHQ/ublox-cellular-rs

I excluded anything that is still on an alpha or hasn't been updated in a year, which adds 5 or so more crates.

That all seems like pretty good coverage the biggest missing ones are atsamd-hal and the stm32 crates (I opened an issue here stm32-rs/stm32f1xx-hal#473 and poked here atsamd-rs/atsamd#332). But embassy covers the STM32 hardware so I wouldn't think this would be too different.

It would be good to have a list of specific crates that are need to be tried with the new interface before making it official.

[rursprung]

thanks a lot for your list, @tgross35 !

your regex is missing some dependencies which are written in a different format. e.g. stm32f4xx-hal supports embedded-hal v1.0.0-alpha.11 (and there's an issue for the RC upgrade: stm32-rs/stm32f4xx-hal#686), so a major stm32 HAL is already supporting it, which should be a good sign 🙂

[adamgreig]

After some discussion last week, we now plan to release the final 1.0 version on Dec 28th, assuming no major issues come up before then. Please keep testing the RC in the meantime!

[madsmtm]

Hey, I've opened a few issues pertaining to the API surface we're stabilizing: #523, #524, #526, #527 and to a lesser extent #525.

I'll volunteer to do the work for each of these, if you think the changes are desired?

Also, this is only the v1.0 release of the embedded-hal crate, right? E.g. the release of v1.0 of embedded-hal-async should probably wait until the async trait functionality reaches stable Rust - at which point its functionality will probably just be included in embedded-hal itself.

Speaking of async, we should probably decide at least a rough plan for how that integration will look like, given that async fn in traits will be stable in 1.75.

[adamgreig]

Thank you for the review and issues!

Not coincidentally, December 28th (the planned e-h 1.0 release) is the day Rust 1.75 is released, and thus the day async traits are in stable Rust, so I think (?) the plan is to release 1.0 of e-h-async at the same time. However, I don't know if there's still a plan to merge it into embedded-hal, though I haven't heard it discussed in some time.

[Finomnis]

I wouldn't be against it :) Although I don't think the plan to do so would interfere with an eh 1.0 release.

[Dirbaio]

this was discussed when we did the split initially, the decision was to leave them split after 1.0.

[Dirbaio]

📣 we just released v1.0.0-rc.3 with a small GPIO trait change (require &mut self in all methods, previously InputPin and StatefulOutputPin required only &self).

We'd appreciate it if you could do another round of testing. Change looks small but InputPin is a quite foundational trait, and the change might have unintended consequences in type inference / method resolution, we'd love to hear if it's causing issues for you.

[eldruin]

I have updated the list of pending issues here. @Dirbaio could you have a look?

[Florob]

I'd like to nominate #455 for the 1.0 release. I.e. specify whether I2C operations can return early like the SPI ones. If so: do we need a flush()?

[Dirbaio]

thanks @eldruin @Florob for bringing these up, I've sent a few PRs and believe they're all cleared now.

[Dirbaio]

No release today, it's going to be delayed a bit due to being blocked on #547

[eldruin]

embedded-hal and embedded-hal-async 1.0.0 have now been released.
Thank you so much to everyone that was worked and helped through all this time to make this a reality.
🎉

[dbrgn]

Thanks a lot to all people involved for pushing this forward week after week over the last 6 years! It's been a while 🙂

Embedded Rust has a bright future ahead! 🦀

[hansfbaier]

Awesome!!!