search

betrusted-io / betrusted-wiki

Looking for docs on Precursor/Betrusted? Start here.
https://github.com/betrusted-io/betrusted-wiki/wiki
Apache License 2.0
173 stars 6 forks source link

Getting Started: add list of on-device commands (help, ver, etc) #22

Closed ewenmcneill closed 1 year ago

ewenmcneill commented 2 years ago

The very well linked https://github.com/betrusted-io/betrusted-wiki/wiki opening page contains a huge amount of useful links/information, but as best I can tell no command reference / no links to command references, for the "on device" commands. I can't obviously find any "on device" command reference in either this Wiki repo, or the other betrusted / xous repos.

It'd be useful to:

And if possible link to a list of all "built in" commands (either, source repo where they're defined, or some documentation).

(FTR, I found enough to get started through the combination of randomly trying "help", having watched someone's live stream about their Precursor unboxing, and the "ver" help.)

bunnie commented 2 years ago

You are correct in observing that there is no command reference for Xous. This is in part because the commands themselves are mostly test routines, and a pass hasn't been made to trim out disused commands and/or to refactor the naming of commands that are rather incorrect now or obsolete (of note are the sleep series of commands that are some of the oldest ones and thus also some of the most inappropriately named commands).

ewenmcneill commented 2 years ago

Possibly "commands you might want to know about" (which are planned to be kept/ "Important Commands") could just be listed in the Getting Started section directly until that pruning is done?

ver in particular was the one I most wanted during updates, to check before/after that it'd worked. (Success, yes, it seems to have worked; although I had to remember that after "ecup auto" I needed to do a "USB power" boot to get it to start up again; I think that's mentioned somewhere, but I couldn't find that again to confirm that was all I was missing.) But I did also wonder if I'd overlooked anything else I should be checking during the three stage update (factory_reset.sh, before/after hard resetting the FPGA with a paperclip, before/after EC update).

(I do appreciate this is basically a "developer edition", so I'm fine with it being pointers to other documentation / source code; it'd just be nice to have something in/linked from the Getting Started page, even if it's "the built in commands are test ones, the only two you probably care about are...." :-) )

Ewen

bunnie commented 2 years ago

You're right that this would probably a good idea to collate somewhere. It's helpful to get feedback like this because actually it's very hard to see from the originating developer's perspective what the gaps are.

unfortunately about all the device can do right now is take an update, and bounce a ball on the screen. There's a wiki page dedicated to updating, but probably there needs to be something in between that and typing "help" at the screen prompt.

ewenmcneill commented 2 years ago

In other "getting started" news, I accidentally discovered there's a menu available (not just a "chat" CLI), via https://github.com/betrusted-io/betrusted-wiki/wiki/Initializing-Root-Keys (press the centre of the arrow cluster). At least it's available after updating the factory firmware to the 2022-03-02 version (0.97 IIRC).

Accessing that "common tasks" menu would also be worth mentioning on a "getting started" "navigating the device" page (probably the same one as "helpful on device commands" for which I created this issue). In particular "sleep now", "backlight on/off", and "set date/time" are all in that menu. (As is the ball demo, which I hadn't previously found: for anyone else, centre of cursor pad for menu, then "Switch to app...", then Simple ball demo.)

(And yes, I agree, it's basically impossible to see these "new users stumble over..." issues after the first couple of days of use; which is one of the reasons I try to record them as I find them :-) )

Ewen

ModestMC commented 2 years ago

I just tried issuing 'sleep wfioff', assuming it would turn the wifi fully off. Instead, it forces it on! (edit, assuming this is indeed the wifi)

Making an initial user's guide to what the device can just do out of the box is a very solid idea. I'd be more than willing to write something up and potentially help with cleaning up the commands.

roll0ver commented 1 year ago

A guide would be most welcome, still haven't figured out how to exit an app or cancel a command to back out of signing xous code if the selection is made in error as an example.

bunnie commented 1 year ago

WIP here: https://github.com/betrusted-io/betrusted-wiki/wiki/Shellchat-Commands

fwiw, you don't really "exit" an app. You just switch to another one using the same method you switched to it. All apps are "live" all the time on Xous (it's not architected to be a multi-tenant system for security reasons, everything should always be considered as "live" for security reasons).

You can't cancel out of signing the OS, unfortunately. That's probably more a subject for an issue, than a documentation problem. If you end up there just pop the paperclip into the hole in the right hand corner if you decided you aren't ready yet and you are at the password dialog box.

bunnie commented 1 year ago

ok, all the commands are now documented. I'll close this, please open an issue if you need any further exposition on commands.

ewenmcneill commented 1 year ago

ok, all the commands are now documented. I'll close this

Thanks very much. That page (https://github.com/betrusted-io/betrusted-wiki/wiki/Shellchat-Commands) is a really good overview of all the shell commands available and which ones are "safe" / "unsafe". Thanks for writing it up.

Ewen