From d1563aa0abaed05c3d26b57c970302be462bde31 Mon Sep 17 00:00:00 2001 From: bunnie Date: Tue, 25 Jan 2022 03:11:50 +0800 Subject: [PATCH] add docs and screenshots --- apps/ball/README.md | 11 ++++++- apps/ball/ball_screenshot.png | Bin 0 -> 3554 bytes apps/repl/README.md | 50 ++++++++++++++++++++++++++++++-- apps/repl/repl_screenshot.png | Bin 0 -> 4676 bytes services/shellchat/README.md | 53 +++------------------------------- 5 files changed, 61 insertions(+), 53 deletions(-) create mode 100644 apps/ball/ball_screenshot.png create mode 100644 apps/repl/repl_screenshot.png diff --git a/apps/ball/README.md b/apps/ball/README.md index b78e5a113..28c029957 100644 --- a/apps/ball/README.md +++ b/apps/ball/README.md @@ -3,7 +3,16 @@ A simple demo application that mainly demonstrates how to integrate into the Xous framework, but without much emphasis on I/O. -## Integration +![screenshot](ball_screenshot.png) + +A ball bounces around, changing directions randomly whenever it hits a border. Pressing +any key will pop up a modal dialog box that informs you of the key pressed, and then +gives you an option to change the behavior into a "tilt" driven mode where the gyro +is read and used to control the ball's motion. + +This is a fairly "raw iron" demo, and would be a reasonable starting point for someone who, +for example, wants to write a video game. +## Copying This App 1. Add a UX context by editing `services/gam/src/lib.rs/EXPECTED_BOOT_CONTEXTS` 2. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`. diff --git a/apps/ball/ball_screenshot.png b/apps/ball/ball_screenshot.png new file mode 100644 index 0000000000000000000000000000000000000000..1a71d427d8a7fd6a62868435ff506d5b5f63d41d GIT binary patch literal 3554 zcmeHKZBUa}7JfsuC|g&p&T9DzV|7^6k&PNb3VHp&^#e#yI<=)p)JRy34Tb1?6MJM6eK0O#HyS6^K!3Kp`QifdmLih%tHd`DSBxXZKHk?BAX7$GK0PxBO!pV?YEWO;rhVyJeEM%3QkeDz9XWzHZ1XVH9D2+i9>_L-1z5O$N4UrsX|~}ze!SYy2;x; z(!p}&yfPbl+_A73!?ls5!tX9(B~6{5Ox0bSJ`*71pJmx!^V#f5`7$_)@UtzE^GrTO z_AM?4!>vix-r1ow5Ojiyh6X)|W0q?xGW}@bvWmE4CFf`LZ(h_ADCxt-t&xQC*LA@l zc{W|#g&C02y!q~K=^O4 z$`uUI1W`#aJvsXZ_Hdh%)CzwgYGP#%h)o*@q+(NCOXsbu;W{TP1Y*rvDV}tW+J`LC zC=q`-{C^&V?biKA*KgnyOoGeq!S&&A(%GiuWe<=?P9rk}VV)}-vZ@|mQ;QI*ey z&g2~r;h79H<<7C!J8}4O5dK;QX}i#)YPt#T9A?Y!uMV~0h>w!uw+I#N4Mw7R>p?=@ zV+xy!mg^hoTq|vsCK(9kD4*T1&i&%L=S2igKkCA)JR)M8j<)iW0=MW6lk2duv$76e zK~d`X3bVnhn@m~1fz?>FLWUvmhx5vtsoG=7*_t3tEN(wKXqpXBYTDfl9_7#|Tx9w( z6$x1iW|_>PL%B1rvf1E%7&?Q4pF3z9uDf5+sPUf43jJ}T($4QtLv2h;SgLh(U8FPd zNW%V+jz(J_2p>zp{mKo5pI<7H3S;ZiVP)MRh%H0x?w(=JOo24`j*!`lZVoq0zH}rJ zx$S5(PW+R&izmp;JfXg!9hqQtiJRO#u>(3!DDTmf5s)vmeTHI{N6&EJSbYsk8 zuSZVz(?D_vX_(J*j^ka4P;`VZuJp+dutNC8cpWeYU|6dTZg>!NbRU^ruvvZbJz-(1 zJXzvH%y1b{_;)VORlY8*xTGpz9=l??l~1{)7Nv^_-cL>v3p^P|z;n&r1-oz2`7Gq*4EQ$>WBtcSXhH%geq~_ zW&T?xvYVK-_`jzERo#1<4%>}mSIrWi+uOi#&fWo4%JK1W`NMpi za{`7%$R+y4k*PvF=iQ5(jOw?!y6^8Te`%R+<~X1@|92ct(&T@dmf5#+X+lj)&{|=2 zRVDMp9^S&WyaTbop&?X;kaN8Tx`K;pM8zds{BZ7hyb=eLt+Q{Bq4@UDI1|w7;zS z8g99wbgJ$1>%9fYweSba!h8oeaZ(pYtomQY46RhDRO)$}biuzg^4~1S&1LTe>gAWC zwmtBh#y$`&>2=%3atKKN0U%r_ycCd#b8z4oRQDDCqo@+ZWw<94yJpybDyAseR#^-K z^vpe$C4=5~L$ddi4VP<0Uu)x1YMkvl)OeuvTY@2muTywx_+y(`j$hBmh}0}trJ9$w uE01r#U_z;KKJttjF$w41@rMFqe1VTz=n9P*f7m~l0eg4h69qdCm;4iZufiMv literal 0 HcmV?d00001 diff --git a/apps/repl/README.md b/apps/repl/README.md index 8a28640b3..b6480842d 100644 --- a/apps/repl/README.md +++ b/apps/repl/README.md @@ -1,12 +1,56 @@ # REPL A simple demo application that provides a bare-bones REPL framework. - -## Integration +## Copying This Demo to a New App 1. Add a UX context by editing `services/gam/src/lib.rs/EXPECTED_BOOT_CONTEXTS` 2. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`. 3. Add it to the Workspace `default-members` and `members` arrays by editing `./Cargo.toml` 4. Add it to the build by editing `xtask/src/main.rs` and inserting it into the relevant descriptor. Typically, you would insert your app into the `hw_pkgs` array, as this is what is built and targeted for full hardware builds. Most of the other trimmed-down descriptors are for debug, emulation, and benchmarking. 5. (optional) You may also need to run `cargo xtask generate-locales` if you modify/add any internationalization strings. -6. Add entries to the app switching menu. `services/status/src/appmenu.rs` to add the menu item (plus `locales/i18n.json` in the status directory if you want translated names for the app), and `services/status/src/main.rs` to add the Opcode (inside the `StatusOpcode` struct, around line 55) and the actual operation itself (in the main `loop`, around line 670). \ No newline at end of file +6. Add entries to the app switching menu. `services/status/src/appmenu.rs` to add the menu item (plus `locales/i18n.json` in the status directory if you want translated names for the app), and `services/status/src/main.rs` to add the Opcode (inside the `StatusOpcode` struct, around line 55) and the actual operation itself (in the main `loop`, around line 670). + +## Details + +![screenshot](repl_screenshot.png) + +`repl` is a baseline demo application for Xous. It uses a chat-client +style interface (stacking bubbles of text, with user input right-aligned +and shell feedback left-aligned) to facilitate interactions. + +It implements the basic envisioned structure of a Xous application, namely: + + - Text input comes via the `ime-frontend` + - Graphical output is rendered via the `gam` + +To make your own command, copy the `audio.rs` template +in the `apps/repl/src/cmds/` directory, or use this very basic `echo` +template: + +```Rust +use crate::{ShellCmdApi, CommonEnv}; +use xous_ipc::String; + +#[derive(Debug)] +pub struct Echo { +} + +impl<'a> ShellCmdApi<'a> for Echo { + cmd_api!(echo); // inserts boilerplate for command API + + fn process(&mut self, args: String::<1024>, _env: &mut CommonEnv) -> Result>, xous::Error> { + Ok(Some(rest)) + } +} +``` + +The "verb" is the name of your command, and it is the argument to the `cmd_api!()` macro. + +`process()` is your "main" function, and `args` is a string which contains the +rest of the line that was typed into the chat, minus the verb used to identify +your command (e.g. the arguments, but not tokenized or parsed in +any way). `env` contains some items in a common environment, for example, connections +to the GAM, LLIO server or other resources required by your implementation. + +Once you've added your command to the directory, go to the `cmds.rs` file, and follow +the four-step instructions embedded within the file, starting around line 40. diff --git a/apps/repl/repl_screenshot.png b/apps/repl/repl_screenshot.png new file mode 100644 index 0000000000000000000000000000000000000000..27dd23d7dda05f019f70816b59d5c0f4ea7216b8 GIT binary patch literal 4676 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 QKY$Bg2l ShellCmdApi<'a> for Echo { - cmd_api!(echo); // inserts boilerplate for command API - - fn process(&mut self, args: String::<1024>, _env: &mut CommonEnv) -> Result>, xous::Error> { - Ok(Some(rest)) - } -} -``` - -The "verb" is the name of your command, and it is the argument to the `cmd_api!()` macro. - -`process()` is your "main" function, and `args` is a string which contains the -rest of the line that was typed into the chat, minus the verb used to identify -your command (the arguments, as they may be, but not tokenized or parsed in -any way). `env` contains some items in a common environment, for example, connections -to the GAM, LLIO server or other resources required by your implementation. - -Once you've added your command to the directory, go to the `cmds.rs` file, and follow -the four-step instructions embedded within the file, starting around line 40. - -## Things to Keep in Mind -- Xous is currently `nostd` -- When you're done adding your command, you should be able to do a `cargo xtask run` and it will fire up an emulated environment, like the one above -- Type...very...slowly...when using the emulated environment. +If you'd like to make your own REPL-type app, check out `apps/repl/` for a pared-down version of +`shellchat` which is a better starting point.