From 8d810dcc51800ea93f394097f1576188de6676cb Mon Sep 17 00:00:00 2001 From: Tom Marble <107828+tmarble@users.noreply.github.com> Date: Wed, 19 Oct 2022 12:50:00 -0500 Subject: [PATCH] Adds mtxcli commands using the PDDB (#246) * Adds mtxcli commands using the PDDB /get key -- shows value of key (from the PDDB) /set key value -- sets value of key (in the PDDB) /unset key -- removes key (from the PDDB) /status -- shows status of the connection Updates .gitignore for PDDB in hosted mode --- .gitignore | 4 +- apps/mtxcli/README.md | 84 ++++++------------ apps/mtxcli/locales/i18n.json | 30 ++++++- apps/mtxcli/src/cmds.rs | 155 ++++++++++++++++++++++----------- apps/mtxcli/src/cmds/get.rs | 47 ++++++++++ apps/mtxcli/src/cmds/help.rs | 33 +++++-- apps/mtxcli/src/cmds/set.rs | 57 ++++++++++++ apps/mtxcli/src/cmds/status.rs | 25 ++++++ apps/mtxcli/src/cmds/unset.rs | 45 ++++++++++ 9 files changed, 362 insertions(+), 118 deletions(-) create mode 100644 apps/mtxcli/src/cmds/get.rs create mode 100644 apps/mtxcli/src/cmds/set.rs create mode 100644 apps/mtxcli/src/cmds/status.rs create mode 100644 apps/mtxcli/src/cmds/unset.rs diff --git a/.gitignore b/.gitignore index 9ce368011..a55fe4d85 100644 --- a/.gitignore +++ b/.gitignore @@ -37,6 +37,9 @@ tools/__pycache__ # PDDB backup files *.pddb +# PDDB for mtxcli (only for testing in hosted mode) +/kernel/mtxcli + # performance monitoring page table tools/ct_data/v2p.txt @@ -72,4 +75,3 @@ share/python-wheels/ .installed.cfg *.egg MANIFEST - diff --git a/apps/mtxcli/README.md b/apps/mtxcli/README.md index 7aff57abb..67cbaf276 100644 --- a/apps/mtxcli/README.md +++ b/apps/mtxcli/README.md @@ -2,70 +2,40 @@ This is a new Matrix chat application which will be derived from REPL. -_NOTE_: constant is in gam/src/lib.rs (APP_NAME_MTXCLI) is generated automatically -with `cargo xtask app-image mtxcli` or `cargo xtask run mtxcli`. +![screenshot](mtxcli_screenshot.png) -# Inherited from REPL +## Background -A simple demo application that provides a bare-bones REPL framework. -## Copying This Demo to a New App +This is a simple [Matrix chat](https://matrix.org/) application based on the REPL framework. -1. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`. -2. Add it to the Workspace `default-members` and `members` arrays by editing `./Cargo.toml` -3. Edit the `manifest.json` file as documented in its [README](../README.md) -4. Build using `cargo xtask app-image you_new_app` to create a flashable Xous image with your app in it. -## Details +## Setup -![screenshot](repl_screenshot.png) +In order to simplify the **mtxcli** application as much as possible the following +must be setup on a conventional device before using Betrusted (laptop, mobile phone). -`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. +* Create a new Matrix user: + * https://matrix.org/faq/#how-do-i-get-an-account-and-get-started%3F +* Find (or create) a new room to join for chatting: + * https://doc.matrix.tu-dresden.de/en/rooms/create/ + * https://spec.matrix.org/latest/#room-structure +* Join the room +* Save the configuration in the pddb + * `/set user @myname:matrix.org` + * `/set password AbigSecret` + * `/set room #my-chat-room` -It implements the basic envisioned structure of a Xous application, namely: +## Commands - - Text input comes via the `ime-frontend` - - Graphical output is rendered via the `gam` +The following commands are available in **mtxcli**: +* `/help [cmd]` -- shows help message for all commands (or one cmd if given) +* `/get key` -- shows value of key (from the PDDB) +* `/set key value` -- sets value of key (in the PDDB) +* `/unset key` -- removes key (from the PDDB) +* `/status` -- shows status of the connection -[Push Events and Listeners](https://github.com/betrusted-io/xous-core/wiki/Push-Events-and-Listeners) provides an overview of the flow of -messages between an Xous application and the Xous Services. +## Chatting -The one demo command provisioned in the `repl` app plays a tone via -the `codec` service. This was chosen because it is about one of the most complicated -and comprehensive things you can do in the `repl` environment, as it requires -real-time callbacks to fill the audio buffer with new samples. If you have -specific questions about how the callbacks work, we encourage you to open -an issue in this repo and ask your question. Your questions will help us -direct effort toward building the documentation base. +Any line not starting with a slash ('/') will be sent to the current room. +New messages from the current room will be displayed. -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. +_NOTE:_ chatting is not implemented yet diff --git a/apps/mtxcli/locales/i18n.json b/apps/mtxcli/locales/i18n.json index 1a033b88a..d780acfc4 100644 --- a/apps/mtxcli/locales/i18n.json +++ b/apps/mtxcli/locales/i18n.json @@ -5,10 +5,16 @@ "zh": "简单的 mtxcli 演示活动", "en-tts": "Welcome to the simple MTXCLI demo." }, + "mtxcli.get.help": { + "en": "/get key", + "ja": "TBD /get key", + "zh": "TBD /get key", + "en-tts": "get key" + }, "mtxcli.help.help": { - "en": "help [cmd]", - "ja": "TBD help [cmd]", - "zh": "TBD help [cmd]", + "en": "/help [cmd]", + "ja": "TBD /help [cmd]", + "zh": "TBD /help [cmd]", "en-tts": "help [cmd]" }, "mtxcli.help.overview": { @@ -17,6 +23,24 @@ "zh": "TBD available mtxcli commands:", "en-tts": "available mtxcli commands:" }, + "mtxcli.set.help": { + "en": "/set key value", + "ja": "TBD /set key value", + "zh": "TBD /set key value", + "en-tts": "set key value" + }, + "mtxcli.status.help": { + "en": "/status", + "ja": "TBD /status", + "zh": "TBD /status", + "en-tts": "status" + }, + "mtxcli.unset.help": { + "en": "/unset key", + "ja": "TBD /unset key", + "zh": "TBD /unset key", + "en-tts": "unset key" + }, "mtxcli.unknown.help": { "en": "unknown command", "ja": "TBD unknown command", diff --git a/apps/mtxcli/src/cmds.rs b/apps/mtxcli/src/cmds.rs index d09823e79..076ccef95 100644 --- a/apps/mtxcli/src/cmds.rs +++ b/apps/mtxcli/src/cmds.rs @@ -1,15 +1,22 @@ use xous::{MessageEnvelope}; -use xous_ipc::String; +use xous_ipc::String as XousString; use core::fmt::Write; use std::collections::HashMap; +use std::fs::File; +use std::io::{Read, Write as StdWrite, Error}; +use std::path::PathBuf; + +/// PDDB Dict for mtxcli keys +const MTXCLI_DICT: &str = "mtxcli"; + /////////////////////////// Common items to all commands pub trait ShellCmdApi<'a> { // user implemented: // called to process the command with the remainder of the string attached - fn process(&mut self, args: String::<1024>, env: &mut CommonEnv) -> Result>, xous::Error>; + fn process(&mut self, args: XousString::<1024>, env: &mut CommonEnv) -> Result>, xous::Error>; // called to process incoming messages that may have been origniated by the most recently issued command - fn callback(&mut self, msg: &MessageEnvelope, _env: &mut CommonEnv) -> Result>, xous::Error> { + fn callback(&mut self, msg: &MessageEnvelope, _env: &mut CommonEnv) -> Result>, xous::Error> { log::info!("received unhandled message {:?}", msg); Ok(None) } @@ -46,25 +53,49 @@ pub struct CommonEnv { codec: codec::Codec, ticktimer: ticktimer_server::Ticktimer, gam: gam::Gam, - cb_registrations: HashMap::>, + cb_registrations: HashMap::>, trng: Trng, xns: xous_names::XousNames, } impl CommonEnv { - /* currently unused - pub fn register_handler(&mut self, verb: String::<256>) -> u32 { - let mut key: u32; - loop { - key = self.trng.get_u32().unwrap(); - // reserve the bottom 1000 IDs for the main loop enums. - if !self.cb_registrations.contains_key(&key) && (key > 1000) { - break; - } - } - self.cb_registrations.insert(key, verb); - key + + pub fn set(&mut self, key: &str, value: &str) -> Result<(), Error> { + log::info!("set '{}' = '{}'", key, value); + let mut keypath = PathBuf::new(); + keypath.push(MTXCLI_DICT); + std::fs::create_dir_all(&keypath)?; + keypath.push(key); + File::create(keypath)?.write_all(value.as_bytes())?; + Ok(()) } - */ + + pub fn unset(&mut self, key: &str) -> Result<(), Error> { + log::info!("unset '{}'", key); + let mut keypath = PathBuf::new(); + keypath.push(MTXCLI_DICT); + std::fs::create_dir_all(&keypath)?; + keypath.push(key); + if std::fs::metadata(&keypath).is_ok() { // keypath exists + std::fs::remove_file(keypath)?; + } + Ok(()) + } + + pub fn get(&mut self, key: &str) -> Result, Error> { + let mut keypath = PathBuf::new(); + keypath.push(MTXCLI_DICT); + std::fs::create_dir_all(&keypath)?; + keypath.push(key); + if let Ok(mut file)= File::open(keypath) { + let mut value = String::new(); + file.read_to_string(&mut value)?; + log::info!("get '{}' = '{}'", key, value); + Ok(Some(value)) + } else { + Ok(None) + } + } + } /* @@ -80,13 +111,21 @@ impl CommonEnv { */ ///// 1. add your module here, and pull its namespace into the local crate +mod get; use get::*; mod help; use help::*; +mod set; use set::*; +mod status; use status::*; +mod unset; use unset::*; pub struct CmdEnv { common_env: CommonEnv, - lastverb: String::<256>, + lastverb: XousString::<256>, ///// 2. declare storage for your command here. + get_cmd: Get, help_cmd: Help, + set_cmd: Set, + status_cmd: Status, + unset_cmd: Unset, } impl CmdEnv { pub fn new(xns: &xous_names::XousNames) -> CmdEnv { @@ -105,59 +144,75 @@ impl CmdEnv { log::info!("done creating CommonEnv"); CmdEnv { common_env: common, - lastverb: String::<256>::new(), + lastverb: XousString::<256>::new(), ///// 3. initialize your storage, by calling new() + get_cmd: Get::new(&xns), help_cmd: Help::new(&xns), + set_cmd: Set::new(&xns), + status_cmd: Status::new(&xns), + unset_cmd: Unset::new(&xns), } } - pub fn dispatch(&mut self, maybe_cmdline: Option<&mut String::<1024>>, maybe_callback: Option<&MessageEnvelope>) -> Result>, xous::Error> { - let mut ret = String::<1024>::new(); + pub fn dispatch(&mut self, maybe_cmdline: Option<&mut XousString::<1024>>, maybe_callback: Option<&MessageEnvelope>) -> Result>, xous::Error> { + let mut ret = XousString::<1024>::new(); let commands: &mut [& mut dyn ShellCmdApi] = &mut [ ///// 4. add your command to this array, so that it can be looked up and dispatched + &mut self.get_cmd, &mut self.help_cmd, + &mut self.set_cmd, + &mut self.status_cmd, + &mut self.unset_cmd, ]; if let Some(cmdline) = maybe_cmdline { let maybe_verb = tokenize(cmdline); - let mut cmd_ret: Result>, xous::Error> = Ok(None); + let mut cmd_ret: Result>, xous::Error> = Ok(None); if let Some(verb_string) = maybe_verb { let verb = verb_string.to_str(); - // search through the list of commands linearly until one matches, - // then run it. - let mut match_found = false; - for cmd in commands.iter_mut() { - if cmd.matches(verb) { - match_found = true; - cmd_ret = cmd.process(*cmdline, &mut self.common_env); - self.lastverb.clear(); - write!(self.lastverb, "{}", verb).expect("couldn't record last verb"); - }; - } - - // if none match, create a list of available commands - if !match_found { - let mut first = true; - write!(ret, "Commands: ").unwrap(); - for cmd in commands.iter() { - if !first { - ret.append(", ")?; - } - ret.append(cmd.verb())?; - first = false; + // if verb starts with a slash then it's a command (else chat) + if verb.starts_with("/") { + // search through the list of commands linearly until one + // matches, then run it. + let command = &verb[1..]; + let mut match_found = false; + for cmd in commands.iter_mut() { + if cmd.matches(command) { + match_found = true; + cmd_ret = cmd.process(*cmdline, &mut self.common_env); + self.lastverb.clear(); + write!(self.lastverb, "{}", verb).expect("couldn't record last verb"); + }; } + + // if none match, create a list of available commands + if !match_found { + let mut first = true; + write!(ret, "Commands: ").unwrap(); + for cmd in commands.iter() { + if !first { + ret.append(", ")?; + } + ret.append("/")?; + ret.append(cmd.verb())?; + first = false; + } + Ok(Some(ret)) + } else { + cmd_ret + } + } else { // chat + write!(ret, "SAY: {} {}", verb, cmdline.to_str()).unwrap(); Ok(Some(ret)) - } else { - cmd_ret } } else { Ok(None) } } else if let Some(callback) = maybe_callback { - let mut cmd_ret: Result>, xous::Error> = Ok(None); + let mut cmd_ret: Result>, xous::Error> = Ok(None); // first check and see if we have a callback registration; if not, just map to the last verb let verb = match self.common_env.cb_registrations.get(&(callback.body.id() as u32)) { Some(verb) => { @@ -190,9 +245,9 @@ impl CmdEnv { /// extract the first token, as delimited by spaces /// modifies the incoming line by removing the token and returning the remainder /// returns the found token -pub fn tokenize(line: &mut String::<1024>) -> Option> { - let mut token = String::<1024>::new(); - let mut retline = String::<1024>::new(); +pub fn tokenize(line: &mut XousString::<1024>) -> Option> { + let mut token = XousString::<1024>::new(); + let mut retline = XousString::<1024>::new(); let lineiter = line.as_str().unwrap().chars(); let mut foundspace = false; diff --git a/apps/mtxcli/src/cmds/get.rs b/apps/mtxcli/src/cmds/get.rs new file mode 100644 index 000000000..9094a718f --- /dev/null +++ b/apps/mtxcli/src/cmds/get.rs @@ -0,0 +1,47 @@ +use crate::{ShellCmdApi,CommonEnv}; +use xous_ipc::String as XousString; +use core::fmt::Write; +use locales::t; + +#[derive(Debug)] +pub struct Get { +} +impl Get { + pub fn new(_xns: &xous_names::XousNames) -> Self { + Get { + } + } +} + +impl<'a> ShellCmdApi<'a> for Get { + cmd_api!(get); + + fn process(&mut self, args: XousString::<1024>, env: &mut CommonEnv) -> Result>, xous::Error> { + let mut ret = XousString::<1024>::new(); + let mut tokens = args.as_str().unwrap().split(' '); + + if let Some(key) = tokens.next() { + match key { + "" => { + write!(ret, "{}", t!("mtxcli.get.help", xous::LANG)).unwrap(); + } + _ => { + match env.get(key) { + Ok(None) => { + write!(ret, "{} is UNSET", key).unwrap(); + }, + Ok(Some(value)) => { + write!(ret, "{}", value).unwrap(); + } + Err(e) => { + write!(ret, "error getting key {}: {:?}", key, e).unwrap(); + log::error!("error getting key {}: {:?}", key, e); + } + } + } + } + } + + Ok(Some(ret)) + } +} diff --git a/apps/mtxcli/src/cmds/help.rs b/apps/mtxcli/src/cmds/help.rs index 98893a402..0e5666918 100644 --- a/apps/mtxcli/src/cmds/help.rs +++ b/apps/mtxcli/src/cmds/help.rs @@ -1,5 +1,5 @@ use crate::{ShellCmdApi,CommonEnv}; -use xous_ipc::String; +use xous_ipc::String as XousString; use core::fmt::Write; use locales::t; @@ -16,20 +16,39 @@ impl Help { impl<'a> ShellCmdApi<'a> for Help { cmd_api!(help); - fn process(&mut self, args: String::<1024>, _env: &mut CommonEnv) -> Result>, xous::Error> { - let mut ret = String::<1024>::new(); + fn process(&mut self, args: XousString::<1024>, _env: &mut CommonEnv) -> Result>, xous::Error> { + let mut ret = XousString::<1024>::new(); let mut tokens = args.as_str().unwrap().split(' '); - // write!(ret, "{}", t!("mtxcli.help.helpting", xous::LANG)).unwrap(); - - if let Some(cmd) = tokens.next() { + if let Some(slashcmd) = tokens.next() { + let cmd = if slashcmd.starts_with("/") { + &slashcmd[1..] + } else { + slashcmd + }; match cmd { + "get" => { + write!(ret, "{}", t!("mtxcli.get.help", xous::LANG)).unwrap(); + } "help" => { write!(ret, "{}", t!("mtxcli.help.help", xous::LANG)).unwrap(); } + "set" => { + write!(ret, "{}", t!("mtxcli.set.help", xous::LANG)).unwrap(); + } + "status" => { + write!(ret, "{}", t!("mtxcli.status.help", xous::LANG)).unwrap(); + } + "unset" => { + write!(ret, "{}", t!("mtxcli.unset.help", xous::LANG)).unwrap(); + } "" => { write!(ret, "{}\n", t!("mtxcli.help.overview", xous::LANG)).unwrap(); - write!(ret, "{}", t!("mtxcli.help.help", xous::LANG)).unwrap(); + write!(ret, "{}\n", t!("mtxcli.get.help", xous::LANG)).unwrap(); + write!(ret, "{}\n", t!("mtxcli.help.help", xous::LANG)).unwrap(); + write!(ret, "{}\n", t!("mtxcli.set.help", xous::LANG)).unwrap(); + write!(ret, "{}\n", t!("mtxcli.status.help", xous::LANG)).unwrap(); + write!(ret, "{}", t!("mtxcli.unset.help", xous::LANG)).unwrap(); } _ => { write!(ret, "{}: {}", diff --git a/apps/mtxcli/src/cmds/set.rs b/apps/mtxcli/src/cmds/set.rs new file mode 100644 index 000000000..fefa6cc37 --- /dev/null +++ b/apps/mtxcli/src/cmds/set.rs @@ -0,0 +1,57 @@ +use crate::{ShellCmdApi,CommonEnv}; +use xous_ipc::String as XousString; +use core::fmt::Write; +use locales::t; + +#[derive(Debug)] +pub struct Set { +} +impl Set { + pub fn new(_xns: &xous_names::XousNames) -> Self { + Set { + } + } +} + +impl<'a> ShellCmdApi<'a> for Set { + cmd_api!(set); + + fn process(&mut self, args: XousString::<1024>, env: &mut CommonEnv) -> Result>, xous::Error> { + let mut ret = XousString::<1024>::new(); + let mut tokens = args.as_str().unwrap().split(' '); + + if let Some(key) = tokens.next() { + match key { + "" => { + write!(ret, "{}", t!("mtxcli.set.help", xous::LANG)).unwrap(); + } + _ => { + if let Some(value) = tokens.next() { + match value { + "" => { + write!(ret, "{}", t!("mtxcli.set.help", xous::LANG)).unwrap(); + } + _ => { + match env.set(key, value) { + Ok(()) => { + write!(ret, "set {} = {}", key, value).unwrap(); + }, + Err(e) => { + write!(ret, "error setting key {}: {:?}", + key, e).unwrap(); + log::error!("error setting key {}: {:?}", + key, e); + } + } + } + } + } else { + write!(ret, "{}", t!("mtxcli.set.help", xous::LANG)).unwrap(); + } + } + } + } + + Ok(Some(ret)) + } +} diff --git a/apps/mtxcli/src/cmds/status.rs b/apps/mtxcli/src/cmds/status.rs new file mode 100644 index 000000000..31e4197e5 --- /dev/null +++ b/apps/mtxcli/src/cmds/status.rs @@ -0,0 +1,25 @@ +use crate::{ShellCmdApi,CommonEnv}; +use xous_ipc::String as XousString; +use core::fmt::Write; +// use locales::t; + +#[derive(Debug)] +pub struct Status { +} +impl Status { + pub fn new(_xns: &xous_names::XousNames) -> Self { + Status { + } + } +} + +impl<'a> ShellCmdApi<'a> for Status { + cmd_api!(status); + + fn process(&mut self, _args: XousString::<1024>, _env: &mut CommonEnv) -> Result>, xous::Error> { + let mut ret = XousString::<1024>::new(); + write!(ret, "status: not connected").unwrap(); + + Ok(Some(ret)) + } +} diff --git a/apps/mtxcli/src/cmds/unset.rs b/apps/mtxcli/src/cmds/unset.rs new file mode 100644 index 000000000..ea9951907 --- /dev/null +++ b/apps/mtxcli/src/cmds/unset.rs @@ -0,0 +1,45 @@ +use crate::{ShellCmdApi,CommonEnv}; +use xous_ipc::String as XousString; +use core::fmt::Write; +use locales::t; + +#[derive(Debug)] +pub struct Unset { +} +impl Unset { + pub fn new(_xns: &xous_names::XousNames) -> Self { + Unset { + } + } +} + +impl<'a> ShellCmdApi<'a> for Unset { + cmd_api!(unset); + + fn process(&mut self, args: XousString::<1024>, env: &mut CommonEnv) -> Result>, xous::Error> { + let mut ret = XousString::<1024>::new(); + let mut tokens = args.as_str().unwrap().split(' '); + + if let Some(key) = tokens.next() { + match key { + "" => { + write!(ret, "{}", t!("mtxcli.unset.help", xous::LANG)).unwrap(); + } + _ => { + match env.unset(key) { + Ok(()) => { + write!(ret, "unset {}", key).unwrap(); + }, + Err(e) => { + write!(ret, "error unsetting key {}: {:?}", + key, e).unwrap(); + log::error!("error unsetting key {}: {:?}", key, e); + } + } + } + } + } + + Ok(Some(ret)) + } +}