numworks / epsilon-sample-app-rust

A sample Rust app for the NumWorks graphing calculator

Sample Rust app for Epsilon

This is a sample Rust app to use on a NumWorks calculator. Yes, you can now use Rust to write code for a graphing calculator!

fn eadk_main() {
    for _ in 0..100 {
        let c = eadk::Color { rgb565: random_u16() };
        let r = eadk::Rect { x: random_coordinate(), y: random_coordinate(), width: random_coordinate(), height: random_coordinate() };
        eadk::display::push_rect_uniform(r, c);
    }
    loop {}
}

Build the app

To build this sample app, you will need to install an embedded ARM rust compiler as well as Node.js. The SDK for Epsilon apps is shipped as an npm module called nwlink that will automatically be installed at compile time.

brew install rustup node # Or equivalent on your OS
rustup-init
rustup target add thumbv7em-none-eabihf
cargo build

Run the app

The app is sent over to the calculator using the DFU protocol over USB.

# Now connect your NumWorks calculator to your computer using the USB cable
cargo run

Notes

The NumWorks calculator runs Epsilon, a tailor-made calculator operating system. Starting from version 16, Epsilon allows installing custom binary apps. To run this sample app, make sure your calculator is up-to-date by visiting https://my.numworks.com.

Due to the embedded nature of Epsilon, the Rust app has to be no_std. The interface that an app can use to interact with the OS is essentially a short list of system calls. Feel free to browse the code of Epsilon itself if you want to get an in-depth look.

Please note that any custom app is removed when resetting the calculator.

License

This sample app is distributed under the terms of the BSD License. See LICENSE for details.

Trademarks

NumWorks and Rust are a registered trademarks.

epsilon-sample-app-rust's Issues

License choise and compatibility with the GNU GPL

The BSD 4-clauses seems like it's not really a good license for this kind of repository, since the whole purpose of the external app system in the beginning was to avoid licensing problems with software using the GNU GPL.

Since this license is incompatible with the GNU GPL, I would suggest to change it for a BSD 3-clauses, which is compatible with said GNU GPL. An even better license would be a MIT license, since it's better suited for thins kind of boilerplate repositories (or even public domain, but I don't think this is ever going to happen).

Make cargo output a .nwa file

I couldn't find how to customize the executable filename. For now the executable is epsilon-sample-app but it should be epsilon-sample-app.nwa.

Apparently it's something you can tweak if you come up with a custom rustc target, but that might be overkill.

Unable to set up an allocator

I'm unable to get an app with an allocator to build. I tried using simple_chunk_allocator to create a small region of memory that I could allocate dynamically.

I set it up like this in the main.rs module.

#![feature(const_mut_refs)]
#![feature(allocator_api)]
#![feature(default_alloc_error_handler)]

static mut HEAP: PageAligned<[u8; 4096]> = heap!(chunks = 256, chunksize = 16);
static mut HEAP_BITMAP: PageAligned<[u8; 2]> = heap_bitmap!(chunks = 16);
#[global_allocator]
static ALLOCATOR: GlobalChunkAllocator =
    unsafe { GlobalChunkAllocator::new(HEAP.deref_mut_const(), HEAP_BITMAP.deref_mut_const()) };

Cargo has no problem building it, but when nwlink runs, I get these errors:

    Finished release [optimized] target(s) in 1.15s
     Running `nwlink install-nwa target/thumbv7em-none-eabihf/release/numworks-app`
Upload [----------------------------------------] 0% | ETA: 0s/home/carson/.nvm/versions/node/v16.9.1/bin/nwlink: app.nwa:(.ARM.exidx.text.__rust_alloc+0x0): undefined reference to `__aeabi_unwind_cpp_pr0'
/home/carson/.nvm/versions/node/v16.9.1/bin/nwlink: app.nwa:(.ARM.exidx.text.__rust_dealloc+0x0): undefined reference to `__aeabi_unwind_cpp_pr0'
/home/carson/.nvm/versions/node/v16.9.1/bin/nwlink: app.nwa:(.ARM.exidx.text.__rust_realloc+0x0): undefined reference to `__aeabi_unwind_cpp_pr0'
/home/carson/.nvm/versions/node/v16.9.1/bin/nwlink: app.nwa:(.ARM.exidx.text.__rust_alloc_error_handler+0x0): undefined reference to `__aeabi_unwind_cpp_pr0'

can't draw rectangles with more than 65637 pixels on Epsilon 18.2.0?

Hello, I was trying to display an image on the whole calculator screen, but strange things happened, sometimes the numworks crashed, other times I couldn't restart the app because "exam mode was enabled" (I never enabled it),
so I tried to figure out where this bug came from and found that if I tried to draw a rectangle with push_rect(rect: Rect, pixels: &[Color]) with more than 65637 white pixels (which is very close to 2^16) , the calculator was crashing, the same thing with more pixels with random colors created weird things like enabling the exam mode or crash when starting other applications.
here is the code:

#[no_mangle]
pub fn main() {
    push_rect(
        Rect {
            x: 0,
            y: 0,
            width: 10,
            height: 10,
        },
        &[Color { rgb565: u16::MAX }; 65637],
    );
}

(The only things I changed other than this are adding #[derive(Clone, Copy) to Color and the build.rs and .cargo/config files)

I don't know much about how numworks works, but I found this bug quite weird and I didn't see any issue about it on the different numworks github repositories
is this normal? is there a fix?

No binding to eadk_keyboard_scan()

eadk.rs does not bind to the eadk_keyboard_scan() system call, so there is currently no way to read key presses.

Does it works in epsilon 18.2.3?

I don't really understand, since epsilon 16, (with n110) the epsilon is supposed to be locked but we can unlock it with Phi. In epsilon 18.2.3 we can't anymore so can we add apps to the numworks even if it is locked?

Build a .bin file in addition to a .nwa file

Ideally we should always build a .bin file along the .nwa file. with nwlink link-nwa. This would let us catch link errors early.

This would need a post-build script which cargo doesn't support just yet.