diff --git a/docs/source/api/index.md b/docs/source/api/index.md new file mode 100644 index 0000000..e0c6a1d --- /dev/null +++ b/docs/source/api/index.md @@ -0,0 +1,6 @@ +# API Reference + +```{toctree} +core.md +views/index.md +``` diff --git a/docs/source/conf.py b/docs/source/conf.py index f60f3d5..a3f7697 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -28,9 +28,11 @@ html_theme_options = { "light_css_variables": { "color-brand-primary": "#FF67E3", + "color-brand-content": "#FF67E3", }, "dark_css_variables": { "color-brand-primary": "#FF67E3", + "color-brand-content": "#FF67E3", }, } diff --git a/docs/source/guides/installing.md b/docs/source/guides/installing.md index 1bed844..a80d2dc 100644 --- a/docs/source/guides/installing.md +++ b/docs/source/guides/installing.md @@ -1,9 +1,9 @@ # Installing -:::{note} +```{note} If you only have the PROS VSCode extension installed, you must run commands in the PROS "Integrated Terminal", not your system terminal. -::: +``` ## Prerequisites @@ -17,7 +17,10 @@ Before you install robodash you must have the following: ## Add the depot -Before adding robodash to your project, you'll need to register the depot with the PROS CLI. A depot is a remote file that informs the PROS CLI of templates that exist and where they can be installed from. You can run the command below to add the depot. +Before adding robodash to your project, you'll need to register the depot with +the PROS CLI. A depot is a remote file that informs the PROS CLI of templates +that exist and where they can be installed from. You can run the command below +to add the depot. ``` pros c add-depot robodash https://raw.githubusercontent.com/unwieldycat/robodash/depot/stable.json @@ -25,11 +28,15 @@ pros c add-depot robodash https://raw.githubusercontent.com/unwieldycat/robodash ### Or don't -Alternatively, you can download and register an individual version of robodash by downloading it from the releases tab on the GitHub page and registering it with `pros c fetch robodash@x.x.x.zip`. This is not recommended since you will have to manually repeat this step as robodash updates. +Alternatively, you can download and register an individual version of robodash +by downloading it from the releases tab on the GitHub page and registering it +with `pros c fetch robodash@x.x.x.zip`. This is not recommended since you will +have to manually repeat this step as robodash updates. ## Apply to project -Now let's add robodash to a project. Open the project you wish to use the robodash in and run the command below to apply it to your project. +Now let's add robodash to a project. Open the project you wish to use the +robodash in and run the command below to apply it to your project. ``` pros c apply robodash diff --git a/docs/source/guides/ui.md b/docs/source/guides/ui.md index 6c22c85..9c28662 100644 --- a/docs/source/guides/ui.md +++ b/docs/source/guides/ui.md @@ -27,4 +27,4 @@ clicking the bell icon to reopen the alert menu. ![Alert button](../img/alert_button.png) If multiple alerts appear, you can view the remaining ones in this menu as well. -The alert button will dissapear once all alerts are dismissed. +The alert button will disappear once all alerts are dismissed. diff --git a/docs/source/guides/usage.md b/docs/source/guides/usage.md index 5d0b987..6a3a73f 100644 --- a/docs/source/guides/usage.md +++ b/docs/source/guides/usage.md @@ -1,66 +1,20 @@ # Using Robodash -Robodash has two parts: the core, and the toolkit. +Robodash provides multiple functionalities for different use cases: -- The core library is the system that enables interoperability between templates - by providing a view-management system for LVGL. This API requires knowledge of - LVGL. Compatible with C and C++. +- If you would like to learn more about Robodash's suite of built-in widgets, + such as the autonomous selector, see the [widgets guide](./usage/widgets.md). -- The toolkit is the set of provided class-based UI tools intended for end users - of the library. These require no knowledge of LVGL and require minimal - configuration. Only compatible with C++. +- If you want to integrate your own LVGL GUIs with Robodash, see the + [views guide](./usage/views.md). -## Toolkit +- If you're a template developer looking to depend on Robodash, check out the + [template guide](./usage/template.md) as well -All of the tools provided by Robodash are class-based, and are designed to be as -simple as possible to use. The following example utilizes the autonomous -selector and the on-screen console. +```{toctree} +:hidden: -```cpp -rd::Selector selector({ - {"Auton 0", &auton0}, - {"Auton 1", &simple_auton}, - {"Skills Run", &skills} -}); - -rd::Console console; - -void initialize() { - console.println("Initializing robot..."); - // Robot stuff would happen... -} - -void autonomous() { - console.println("Running auton..."); - selector.run_auton(); -} +./usage/views.md +./usage/widgets.md +./usage/template.md ``` - -Documention for each class is linked on the topics page. - -## Core - -The core library is the view management system for LVGL, and is designed to be -as familliar as possible to someone already familliar with LVGL. Each view, -represented by a memory pointer to an `rd_view_t`, exposes an LVGL object the -size of the view area, which can be thought of as a screen. It is very important -that any LVGL objects that are created in your template or user program are a -child of this exposed object, **NOT `lv_scr_act()`**, since robodash manages -which view is active by hiding and unhiding the object cooresponding to each -view. - -The name passed to each view will be the name that is displayed on screen in the -view switcher and any alert dialogues spawned by the view. - -The following is an example of a simple view that displays a text label. - -```cpp -void opcontrol() { - rd_view_t *view = rd_view_create("custom view"); - lv_label_t *label = lv_label_create(rd_view_obj(view)); - lv_label_set_text(label, "example"); - lv_obj_align(label, LV_ALIGN_CENTER, 0, 0); -} -``` - -You can learn more about the core library at the [Core Reference](../api/core.md) page. diff --git a/docs/source/guides/usage/template.md b/docs/source/guides/usage/template.md new file mode 100644 index 0000000..bc8d418 --- /dev/null +++ b/docs/source/guides/usage/template.md @@ -0,0 +1,20 @@ +# Template Integration + +When depending on Robodash, it is recommended that you follow these instructions +for better user ease of use. + +- **Do not bundle Robodash with your template** - It is not recommended that you + add Robodash's source files to your template and distribute it with your own + template. This prevents users from upgrading unless your own template + upgrades, and places the burden on you to upgrade your template when Robodash + upgrades. For new users, it is recommended instead to have a "starter project" + that is pre-configured with Robodash and your own template. + +- **Inform users that your template uses Robodash** - You should inform users + that your template depends on Robodash so they know to install it. + Additionally, provide some form of guidance for installing Robodash (a link to + these docs or your own instructions). You should also indicate which version + of Robodash your template uses, so users know what versions they can use. + +- **Do not modify Robodash** - No modifications should be made to Robodash's + header or source files, and no additions should be made to its namespace. diff --git a/docs/source/guides/usage/views.md b/docs/source/guides/usage/views.md new file mode 100644 index 0000000..0079b95 --- /dev/null +++ b/docs/source/guides/usage/views.md @@ -0,0 +1,30 @@ +## Views + +Robodash provides the views API for other LVGL-powered GUIs to plug into its +view-management system. + +Below is an example on creating a view called "my view". + +```cpp +rd_view_t *view = rd_view_create("my view"); +``` + +Creating a view will return a pointer to an `rd_view_t`, which holds the name of +the view and the LVGL object for the view. The name passed to the view +constructor will be the name that is displayed on screen in the view switcher +and any alert dialogues spawned by the view. The view's LVGL object should +parent any LVGL UI that is a part of that view, since this is how Robodash +changes which view is currently active on the screen. **Any instance of +`lv_scr_act()` in your LVGL GUI code should be replaced with +`lv_view_obj(your_view)`.** + +The following is an example of a simple view that displays a text label. + +```cpp +rd_view_t *view = rd_view_create("custom view"); +lv_label_t *label = lv_label_create(rd_view_obj(view)); +lv_label_set_text(label, "example"); +lv_obj_align(label, LV_ALIGN_CENTER, 0, 0); +``` + +[Views API Reference](../../api/core.md) page. diff --git a/docs/source/guides/usage/widgets.md b/docs/source/guides/usage/widgets.md new file mode 100644 index 0000000..6ba9872 --- /dev/null +++ b/docs/source/guides/usage/widgets.md @@ -0,0 +1,83 @@ +# Widgets + +Robodash provides a suite of simple, commonly used GUI widgets. + +## Selector + +The [Selector Widget](../../api/views/selector.md) is a function selector +designed for managing autonomous runs. + +To use the selector we can construct it in the global scope of our `main.cpp` +file. + +```cpp +rd::Selector selector({ + {"Best auton", best_auton}, + {"Simple auton", simple_auton}, + {"Good auton", good_auton}, +}); +``` + +The selector's constructor takes a vector of pairs that hold a string and a +function. The string is the name that appears on the display as the function's +name, and the function is what is called when it is selected. + +Our example assumes we have three functions, `best_auton`, `simple_auton`, and +`good_auton`. These functions should take no arguments and return `void`. + +While the selector appears on the screen, we still need to make our selected +routine run when our bot is in autonomous mode. + +In your `main.cpp` file, call `selector.run_auton()` in your `autonomous` +function. + +```cpp +void autonomous() { + selector.run_auton(); +} +``` + +Now, when our robot is in autonomous mode, our user-selected routine will run. +In addition, if an SD card is in the brain, the selected routine will be +preserved next time the program is run. + +## Console + +The [Console Widget](../../api/views/console.md) provides a text display for +quickly and easily displaying information for debugging. To create a console, we +can construct it in our `main.cpp` file's global scope. + +```cpp +rd::Console console; +``` + +We can now log information to the console with `console.print`, +`console.println`, and `console.printf`, and we can clear the console with +`console.clear`. + +```cpp +console.println("Hello"); +console.printf("The robot's heading is %f\n", some_imu.get_heading()); +``` + +## Image + +The [Image Widget](../../api/views/image.md) provides a way to display LVGL +images to the LCD. + +Images displayed must be converted with the +[LVGL image converter](https://lvgl.io/tools/imageconverter) for LVGL 8. You can +convert the image to a C array and place it in your project's `src` directory, +or convert it to a a binary file and load it onto a microSD card. + +To create an image, we can construct it with a path to an LVGL-converted +`image.bin` file on a loaded SD card, or to an LVGL image variable. You also +must pass a name to the image. + +```cpp +// microSD approach +rd::Image image1("S:/usd/logo.bin", "Team Logo"); + +// C array approach +rd::Image image2(team_logo, "Team Logo") +``` diff --git a/docs/source/index.md b/docs/source/index.md index bbe63a7..e42afad 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -43,8 +43,8 @@ guides/ui.md ```{toctree} :hidden: -:caption: API Reference +:caption: Reference -api/core.md -api/views/index.md +api/index.md +LVGL 8.3 Docs ```