Skip to content

Home

Jump to bottom Edit New page
Jeanie edited this page Dec 10, 2024 · 140 revisions

Get Started

For help, you can open a github issue in the appropriate repo, or join the Matrix chat.

First - Update Your Precursor Device

Next - Set up Security

After these steps, your basic Precursor is be ready to be used.

  • Factory reset - if you forget your login password or want to dispose of or resell your device

Installing Additional Apps

  • Out of the box, the basic firmware image for Precursor comes with shellchat and vault apps.
  • Apps are statically loaded programs, linked into the firmware image.
  • To add additional apps, build a custom firmware image and load it onto your Precursor.

Currently Available Apps include:

  • Shellchat - the default app when you power on.
  • Vault - a physical password vault. Make, store, and autotype passwords; generate TOTP codes; and perform FIDO2/U2F authentication. Perhaps the only hardware FIDO token with secure backups.
  • Matrix client - a simple Matrix chat application.
  • Mtxchat - next-gen matrix client, currently WIP.
  • Transientdisk - present a 1.44MiB RAM drive to a host over USB. Contents are cleared when the app is closed, or the device is put to sleep. Useful for transferring secret keys over short distances.

Reminder: Backup your Precursor.

  • Backups - the thing you think you'll never need. Until you do. Highly recommended.

Writing code for Xous (and Precursor)

Running the emulator

  • Run cargo xtask run, and it will pop up a "host-mode" emulated version of Precursor.
  • To add additional apps other than the default, add them after run, like cargo xtask run hello ball (will build and add both the hello and ball apps)
    • check cargo xtask --help for the full list of commands and options.
    • Hosted emulator uses Home (Fn+⬅ on Mac) for the center key on the Precursor device, use this button when navigating within the emulator.

Build troubleshooting

  • If you get a build error, try updating to the latest rust with rustup update
  • If you have updated rust or have tinkered with std on your system, you can re-install the xous target with cargo xtask install-toolkit --force, and then run rm -r target to force remove stale build files.
  • You may also need to install some additional libraries, such as libxkbdcommon-dev.
  • Xous has generally been tracking the latest stable Rust toolchain, so if your build isn't working, try updating to the latest stable Rust, or if there was just a release, try one version before the latest version. Alternatively, you can check the CI logs for the version used in the last stable build, by searching for rustc --version in the log.
    • To set the toolchain version, run rustup override set 1.64 (or which ever version you're trying to target).
    • Arch Linux users: Hoverbear has written a guide for setting up Xous on Arch Linux!

Making your own app

Reference Apps

  • repl app demo is the starting point for users who want to interact with their device by typing commands. This demo leverages more of the Xous UX built-in frameworks.
  • ball app demo is the starting point for users who prefer to run close to the bare iron, getting only key events and a framebuffer for crafting games and bespoke apps.

Ready to add your own app?

  • Please refer to the manifest.json documentation for integration notes.
  • ⚠️ hosted mode is literally Xous running on your local host, which means it supports more features than Xous on native hardware:
    • We do not have tokio support planned anytime soon.
    • We do not have File support in Xous; instead, we have the pddb.
    • Net support in actively in development and we hope to have fairly robust support for libstd Net but, note that socket2 crate (which is not part of Rust libstd) does not recognize Xous as a supported host.
  • It is recommended to try compiling your configuration for a real hardware target or Renode early on to confirm compatibility, before doing extensive development in hosted mode.
  • Currently, the only hardware implementation of the project referenced in this repo is the Precursor device. If you port Xous to a new platform, please reference the target right here in this wiki!
  • For how to implement localized strings, please see the locales readme.

Getting past Hello World

In Depth

Organized, roughly, from top of the stack and drilling into the hardware.

Xous: Applications

  • App manifest and adding apps
  • GDB is available with a custom-built kernel using the argument --gdb-stub. GDB is mainly tested for the Renode target; it should work for "real" hardware as well but it is not as well tested.

Xous: OS Services

Xous: Microkernel Core

Pre-Boot & Security

Between the Software and Hardware: Hardware Abstractions

  • UTRA Hardware register access abstraction for Xous
  • Peripheral access conventions Goals for hardware register abstractions
  • COM Protocol between the embedded controller (EC) and the main SoC

Hardware Documentation

TRNG Chronicles

Audit Trail

  • crate-scraper is the beginning of a tool that helps with audit trails. It saves all the source code derived from crates.io to build Xous, and collates all the build.rs files into a single mega-file for faster manual inspection.

Meta-Issues

External Talks and Papers

Other Documents of Interest

Acknowledgments

This project is funded in part through the NGI0 PET Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 825310.

Add a custom footer
Add a custom sidebar
Clone this wiki locally