1 files changed, 64 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d037d41
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# rust-threadx-demos
+
+These demos use ThreadX as a Rust standard library implementation.
+They work in / on
+
+- QEMU
+- a Teensy 4.0
+- an iMXRT1170EVK
+
+Right now, they blink LEDs and / or print `"hello world!"`.
+
+These demos are for [my RustConf 2026 talk][project-landing]!
+
+[project-landing]: https://www.mciantyre.dev/projects/rust-std-on-threadx/
+
+## Getting started
+
+You'll need a custom toolchain to build these examples.
+[Here][project-landing] is how to build that toolchain.
+All commands below assume your toolchain keeps the `stage1` name.
+
+### QEMU
+
+Install `qemu-system-arm` for your host.
+Then, run the example:
+
+```
+cargo +stage1 --config .cargo/qemu.toml run --release --package=rust-threadx-qemu
+```
+
+QEMU's stdio uses semihosting for input and output.
+
+### Teensy 4.0
+
+You'll need a Teensy 4.0 board.
+[Install the dependencies][teensy4-rs] discussed in the teensy4-rs project, including the command-line `teensy_loader_cli`.
+Also, [install the teensy4-runner][teensy4-runner].
+
+[teensy4-rs]: https://github.com/mciantyre/teensy4-rs
+[teensy4-runner]: https://github.com/mciantyre/teensy4-rs/tree/master/tools
+
+Run the following to compile the example, convert it to Intel HEX, and attempt board programming:
+
+```
+cargo +stage1 --config .cargo/teensy4.toml run --release --package=rust-threadx-teensy4
+```
+
+Once running on your board, you should see the LED blinking.
+Connect to the USB serial interface to see the welcome message.
+The board's stdio uses USB serial for stdout; stdin is not (yet) implemented.
+
+### iMXRT1170EVK
+
+You'll need the board and a recent build of [probe-rs].
+Run the following to compile and flash the example:
+
+[probe-rs]: https://probe.rs
+
+```
+cargo +stage1 --config .cargo/imxrt1170evk.toml run --release --package=rust-threadx-imxrt1170evk
+```
+
+You should see the LED blinking.
+The board's stdio uses semihosting for input and output; probe-rs should automatically detect this.