{"id":16221590,"url":"https://github.com/rahix/shared-bus","last_synced_at":"2025-04-04T15:07:54.567Z","repository":{"id":32862726,"uuid":"144606067","full_name":"Rahix/shared-bus","owner":"Rahix","description":"Crate for sharing buses between multiple devices","archived":false,"fork":false,"pushed_at":"2024-02-26T15:08:49.000Z","size":109,"stargazers_count":132,"open_issues_count":14,"forks_count":34,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-01T15:58:12.437Z","etag":null,"topics":["embedded-hal","embedded-rust","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rahix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-13T16:31:26.000Z","updated_at":"2025-03-25T22:45:53.000Z","dependencies_parsed_at":"2023-01-14T22:27:59.935Z","dependency_job_id":"ed14928f-0fec-4d14-ad04-0c1ce591f6a5","html_url":"https://github.com/Rahix/shared-bus","commit_stats":{"total_commits":80,"total_committers":10,"mean_commits":8.0,"dds":"0.21250000000000002","last_synced_commit":"b72ac01e67883724fc364049b3b9f7232303375a"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rahix%2Fshared-bus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rahix%2Fshared-bus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rahix%2Fshared-bus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rahix%2Fshared-bus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rahix","download_url":"https://codeload.github.com/Rahix/shared-bus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198450,"owners_count":20900080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded-hal","embedded-rust","rust"],"created_at":"2024-10-10T12:09:00.899Z","updated_at":"2025-04-04T15:07:54.541Z","avatar_url":"https://github.com/Rahix.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"shared-bus [![crates.io page](https://img.shields.io/crates/v/shared-bus)](https://crates.io/crates/shared-bus) [![docs.rs](https://docs.rs/shared-bus/badge.svg)](https://docs.rs/shared-bus) [![Continuous Integration](https://github.com/Rahix/shared-bus/actions/workflows/ci.yml/badge.svg)](https://github.com/Rahix/shared-bus/actions/workflows/ci.yml)\n==========\n\n**shared-bus** is a crate to allow sharing bus peripherals safely between multiple devices.\n\nIn the `embedded-hal` ecosystem, it is convention for drivers to \"own\" the bus peripheral they\nare operating on.  This implies that only _one_ driver can have access to a certain bus.  That,\nof course, poses an issue when multiple devices are connected to a single bus.\n\n_shared-bus_ solves this by giving each driver a bus-proxy to own which internally manages\naccess to the actual bus in a safe manner.  For a more in-depth introduction of the problem\nthis crate is trying to solve, take a look at the [blog post][blog-post].\n\nThere are different 'bus managers' for different use-cases:\n\n# Sharing within a single task/thread\nAs long as all users of a bus are contained in a single task/thread, bus sharing is very\nsimple.  With no concurrency possible, no special synchronization is needed.  This is where\na [`BusManagerSimple`] should be used:\n\n```rust\n// For example:\nlet i2c = I2c::i2c1(dp.I2C1, (scl, sda), 90.khz(), clocks, \u0026mut rcc.apb1);\n\nlet bus = shared_bus::BusManagerSimple::new(i2c);\n\nlet mut proxy1 = bus.acquire_i2c();\nlet mut my_device = MyDevice::new(bus.acquire_i2c());\n\nproxy1.write(0x39, \u0026[0xc0, 0xff, 0xee]);\nmy_device.do_something_on_the_bus();\n```\n\nThe `BusManager::acquire_*()` methods can be called as often as needed; each call will yield\na new bus-proxy of the requested type.\n\n# Sharing across multiple tasks/threads\nFor sharing across multiple tasks/threads, synchronization is needed to ensure all bus-accesses\nare strictly serialized and can't race against each other.  The synchronization is handled by\na platform-specific [`BusMutex`] implementation.  _shared-bus_ already contains some\nimplementations for common targets.  For each one, there is also a macro for easily creating\na bus-manager with `'static` lifetime, which is almost always a requirement when sharing across\ntask/thread boundaries.  As an example:\n\n```rust\n// For example:\nlet i2c = I2c::i2c1(dp.I2C1, (scl, sda), 90.khz(), clocks, \u0026mut rcc.apb1);\n\n// The bus is a 'static reference -\u003e it lives forever and references can be\n// shared with other threads.\nlet bus: \u0026'static _ = shared_bus::new_std!(SomeI2cBus = i2c).unwrap();\n\nlet mut proxy1 = bus.acquire_i2c();\nlet mut my_device = MyDevice::new(bus.acquire_i2c());\n\n// We can easily move a proxy to another thread:\n# let t =\nstd::thread::spawn(move || {\n    my_device.do_something_on_the_bus();\n});\n# t.join().unwrap();\n```\n\nThose platform-specific bits are guarded by a feature that needs to be enabled.  Here is an\noverview of what's already available:\n\n| Mutex | Bus Manager | `'static` Bus Macro | Feature Name |\n| --- | --- | --- | --- |\n| `std::sync::Mutex` | [`BusManagerStd`] | [`new_std!()`] | `std` |\n| `cortex_m::interrupt::Mutex` | [`BusManagerCortexM`] | [`new_cortexm!()`] | `cortex-m` |\n| `shared_bus::XtensaMutex` (`spin::Mutex` in critical section) | [`BusManagerXtensa`] | [`new_xtensa!()`] | `xtensa` |\n| NA | [`BusManagerAtomicCheck`] | [`new_atomic_check!()`] | `cortex-m` |\n\n# Supported Busses\nCurrently, the following busses can be shared with _shared-bus_:\n\n| Bus | Proxy Type | Acquire Method | Comments |\n| --- | --- | --- | --- |\n| I2C | [`I2cProxy`] | [`.acquire_i2c()`] | |\n| SPI | [`SpiProxy`] | [`.acquire_spi()`] | SPI can only be shared within a single task (See [`SpiProxy`] for details). |\n| ADC | [`AdcProxy`] | [`.acquire_adc()`] | |\n\n\n[`.acquire_i2c()`]: https://docs.rs/shared-bus/latest/shared_bus/struct.BusManager.html#method.acquire_i2c\n[`.acquire_spi()`]: https://docs.rs/shared-bus/latest/shared_bus/struct.BusManager.html#method.acquire_spi\n[`.acquire_adc()`]: https://docs.rs/shared-bus/latest/shared_bus/struct.BusManager.html#method.acquire_adc\n[`BusManagerCortexM`]: https://docs.rs/shared-bus/latest/shared_bus/type.BusManagerCortexM.html\n[`BusManagerSimple`]: https://docs.rs/shared-bus/latest/shared_bus/type.BusManagerSimple.html\n[`BusManagerAtomicCheck`]: https://docs.rs/shared-bus/latest/shared_bus/type.BusManagerAtomicCheck.html\n[`BusManagerStd`]: https://docs.rs/shared-bus/latest/shared_bus/type.BusManagerStd.html\n[`BusManagerXtensa`]: https://docs.rs/shared-bus/latest/shared_bus/type.BusManagerXtensa.html\n[`BusMutex`]: https://docs.rs/shared-bus/latest/shared_bus/trait.BusMutex.html\n[`I2cProxy`]: https://docs.rs/shared-bus/latest/shared_bus/struct.I2cProxy.html\n[`SpiProxy`]: https://docs.rs/shared-bus/latest/shared_bus/struct.SpiProxy.html\n[`AdcProxy`]: https://docs.rs/shared-bus/latest/shared_bus/struct.AdcProxy.html\n[`new_cortexm!()`]: https://docs.rs/shared-bus/latest/shared_bus/macro.new_cortexm.html\n[`new_atomic_check!()`]: https://docs.rs/shared-bus/latest/shared_bus/macro.new_atomic_check.html\n[`new_xtensa!()`]: https://docs.rs/shared-bus/latest/shared_bus/macro.new_xtensa.html\n[`new_std!()`]: https://docs.rs/shared-bus/latest/shared_bus/macro.new_std.html\n[blog-post]: https://blog.rahix.de/001-shared-bus\n\n## License\nshared-bus is licensed under either of\n\n * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahix%2Fshared-bus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frahix%2Fshared-bus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahix%2Fshared-bus/lists"}