example of an unsafe call into ESP IDF

Author: ivmarkov

.github/configs/sdkconfig.defaults

@@ -1,3 +1,6 @@
 # The examples require a larger than the default stack size for the main thread and the posix threads.
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=20000
 CONFIG_PTHREAD_TASK_STACK_SIZE_DEFAULT=8192
+
+# Go figure...
+CONFIG_FREERTOS_IDLE_TASK_STACKSIZE=4096

CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [?.??.?] - ????-??-??
+* First `esp-idf-sys` examples:
+  * `std_basics`: "Hello world" with `println!` and other types available in the Rust Standard Library like threads, atomics, local storage, collections, etc.
+  * `unsafe_call`: Calling an ESP IDF custom API using the unsafe bindings generated by `esp-idf-sys`
 * All FreeRTOS headers are now included, so user should get unsafe bindings for all FreeRTOS APIs which are not macros
 * Changes to how native vs PlatformIO build is selected, that are supposed to increase the ergonomics of using the crate:
   * Perform PlatformIO build **only** when the `pio` feature IS specified, and the `native` feature is NOT specified

examples/std_basics.rs

@@ -1,3 +1,7 @@
+//! This example does not use anything from the `esp-idf-sys` unsafe API
+//! but demonstrates, that *linking* with the `esp-idf-sys` library artefacts (and with the Rust Standard Library)
+//! does provide the Rust STD layer on top of ESP IDF!
+
 use core::cell::RefCell;
 use core::ptr;
 use core::sync::atomic::{AtomicUsize, Ordering};

examples/unsafe_call.rs

@@ -0,0 +1,12 @@
+//! A super-simple example of calling an unsafe API provided by `esp-idf-sys` / ESP IDF
+//! and not otherwise available via the Rust Standard Library
+
+use esp_idf_sys::esp_get_free_heap_size;
+
+fn main() {
+    esp_idf_sys::link_patches();
+
+    let free_memory = unsafe { esp_get_free_heap_size() } / 1024;
+
+    println!("Free memory: {free_memory}KB");
+}