{"id":20415436,"url":"https://github.com/riot-os/rust-riot-wrappers","last_synced_at":"2025-04-12T17:06:38.268Z","repository":{"id":37900803,"uuid":"498388466","full_name":"RIOT-OS/rust-riot-wrappers","owner":"RIOT-OS","description":"The `riot-wrappers` crate, which enables high-level access to RIOT from the Rust programming language","archived":false,"fork":false,"pushed_at":"2025-02-21T23:26:55.000Z","size":954,"stargazers_count":16,"open_issues_count":25,"forks_count":12,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-04-12T17:06:05.817Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RIOT-OS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-05-31T15:15:58.000Z","updated_at":"2025-04-09T10:21:42.000Z","dependencies_parsed_at":"2024-04-03T22:28:09.707Z","dependency_job_id":"73efbfc8-cf46-423c-a538-b33fc4645c65","html_url":"https://github.com/RIOT-OS/rust-riot-wrappers","commit_stats":{"total_commits":576,"total_committers":4,"mean_commits":144.0,"dds":0.01736111111111116,"last_synced_commit":"fbc6cfe86f8b256427f15f18b4c945483ff2bcfc"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RIOT-OS%2Frust-riot-wrappers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RIOT-OS%2Frust-riot-wrappers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RIOT-OS%2Frust-riot-wrappers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RIOT-OS%2Frust-riot-wrappers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RIOT-OS","download_url":"https://codeload.github.com/RIOT-OS/rust-riot-wrappers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248602311,"owners_count":21131615,"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":[],"created_at":"2024-11-15T06:16:07.498Z","updated_at":"2025-04-12T17:06:38.262Z","avatar_url":"https://github.com/RIOT-OS.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"This crate contains wrappers around the [RIOT Operating\nSystem](https://riot-os.org/)'s C API exposed by riot-sys and\nmakes an attempt to provide idiomatic Rust wrappers (eg. implementing\nembedded-hal for peripherals, implementing fmt::Write for stdio) around those.\n\nThe [crate documentation](https://doc.riot-os.org/rustdoc/latest/riot_wrappers/) outlines which\nmodules are available, and which other crates' traits they implement.\n\nFor a newcomer's starting point, see [RIOT's documentation on using it with Rust].\nFor basic code examples see [RIOT's examples](https://github.com/RIOT-OS/RIOT/tree/master/examples/lang_support/official)\n(those with \"rust\" in their name), and the\n[additional examples](https://gitlab.com/etonomy/riot-examples/)\nwhich showcase more of the wrapped APIs.\n\n[RIOT's documentation on using it with Rust]: https://doc.riot-os.org/using-rust.html\n\nLibrary and run-time components\n-------------------------------\n\nThe riot-wrappers crate tries to stay out of the way by default to enable\nvarious types of applications (ie. not only \"Rust application running atop\nRIOT\", but also \"RIOT module / driver implemented in Rust\" or others).\n\nTo facilitate what is currently the best explored use case (\"Rust application\nrunning atop RIOT\"), applications can use the ``main!`` macro to wrap a regular\nRust function like ``fn main() -\u003e ()`` into a function that's exported with\nproper name and signature to serve as ``main`` function in RIOT.\n\nWhen that is used, it also makes sense to enable the ``set_panic_handler``\nfeature. It implements a panic handler that outputs the panic message to RIOT's\nstandard output, and puts the affected thread to sleep permanently.  (There is\nno unwinding or similar; threads in RIOT are not really expected to terminate\nand be restarted).\n\nWith such a main function and panic handler, a Rust crate can be built as a\nstatic library and linked as a part of the RIOT build process without the need\nfor application specific C code. The RIOT build system automates that linking,\nand examples of the setup required in Cargo.toml and Makefile are available as\npart of RIOT's example directory.\n\nSupported RIOT \u0026 Rust versions\n------------------------------\n\nCurrently, this crate targets the latest development version of RIOT.\nSupport for the latest release is maintained on a best-effort basis.\n\nThis crate has no MSRV, it may start depending on the latest stable as soon as RIOT's build infrastructure has it.\n\nWhen a released version of RIOT is used with anything but the riot-sys / riot-wrappers / nightly-compiler combination it was released with,\nit is likely that all these must be upgraded together.\n\nIn terms of public API,\nriot-wrappers aims to uphold SemVer guarantees\n(with little exceptions explicitly documented with the relevant items,\nsuch as reserving the right to replace a type with a `pub use` from the standard library once a feature is stabilized).\nUnlike that of riot-sys,\nthis API is stable across releases of RIOT.\n\nOn item presence and modules\n----------------------------\n\nThis crate makes some of its modules' presence conditional on whether the\ncorresponding RIOT module is active in the build configuration; that\ninformation is obtained by inspecting the `riotbuild.h file`. For example,\n`riot_wrappers::saul` is only present if `USEMODULE += saul` is (directly or\nindirectly) set in the Makefile.\n\nThis makes things very auto-magical, and I'm not yet sure whether that's the\nbest way for things to be. The Cargo way would be that the crate using\nriot-wrappers actively enables some features in riot-wrappers -- but the crate\ncan not act on RIOT's module selection, as by the time it is called, RIOT is\nalready configured. The RIOT way would be to enable the modules the application\nneeds in the Makefile (possibly with dependencies pulling others in), but the\ncrate not being a module makes that hard.\n\nThis automagic way is convenient now; later iterations might be more explicit\nand profit from better integration.\n\nCode conventions\n----------------\n\nThere is a [contributing guide](CONTRIBUTING.md) for this repository.\n\nIn older pieces of code (predating the use of C2Rust), static inline RIOT functions\nor expanded macros are used. To keep track of them, comments in the shape of\n``EXPANDED ${FILE}:${LINE}`` are set (referring to line numbers in RIOT commit 6b96f69b).\n\nAs these are being replaced by using C2Rust idioms, conflicts between C2Rust's\nand bindgen's versions of structs arise instead, typically around pointers. When these\nare cast away, they're fed through `inline_cast` \u0026 co to perform some checks,\nor commented with ``INLINE TRANSMUTE`` for the very hard cases.\n\nLicense\n-------\n\nThis crate is dual-licensed under the same terms of the MIT license or the\nApache 2.0 license, as is commonplace in the embedded Rust ecosystem.\n\nNote that it crate depends on `riot-sys`, which is licensed under RIOT's LGPL\n2.1 to reflect that it uses code transpiled from RIOT.\n\nThe crate is maintained by Christian Amsüss \u003cchrysn@fsfe.org\u003e as part of the etonomy\nproject, see \u003chttps://etonomy.org/\u003e, and the RIOT team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friot-os%2Frust-riot-wrappers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friot-os%2Frust-riot-wrappers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friot-os%2Frust-riot-wrappers/lists"}