Skip to content

Commit

Permalink
update README
Browse files Browse the repository at this point in the history
Signed-off-by: Teo Koon Peng <[email protected]>
  • Loading branch information
koonpeng committed Sep 19, 2024
1 parent 4c0de1c commit 2ff9f39
Showing 1 changed file with 34 additions and 68 deletions.
102 changes: 34 additions & 68 deletions packages/rmf-dashboard-framework/README.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,16 @@
# rmf-dashboard
# rmf-dashboard-framework

`rmf-dashboard` is a web application that provides overall visualization and control over the RMF system.
`rmf-dashboard-framework` is a library that makes it easy to build a web application that provides visualization and control over the RMF system.

# Setup
## Getting Started

Follow the build instructions [here](../../README.md/#launching).
See the [Getting Started](./docs/getting-started.md) docs.

## Configuration
## MicroApps

Before building the dashboard, you must configure it according to the deployment. All the configurations is on `app-config.json`, the default configuration is for running the api-server and dashboard locally. You may check [src/app-config.ts](src/app-config.ts) for more details on the config file schema.
MicroApps are react components that can be used to build a page. The dashboard comes with many different micro-apps, each serving a different purpose when interacting with an Open-RMF deployment. The dashboard uses events to pipe information between micro-apps, for example clicking onto a task row in the Task app, will center the map onto the robot that the task was assigned to.

### (Optional) Add external resources.

The `resources` option in the app config allows configuring various assets used by the dashboard. At the moment, it mainly allows configuring the header logo and robot icons, they should point to either the full url or absolute url, for example

```json
"resources": {
"default": {
"fleets": {
"tinyRobot": {
"default": {
"icon": "https://raw.githubusercontent.com/open-rmf/rmf_demos/rmf-web-dashboard-resources/rmf_demos_dashboard_resources/office/icons/tinyRobot.png",
"scale": 0.00123
}
}
},
"logos": {
"header": "/resources/defaultLogo.png"
}
}
},
```

In the above config, the header logo will be on absolute url `/resources/defaultLogo.png`, if the resources are hosted on a different domain (e.g. you are using a cdn), then it should include the full url, e.g. `https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]`.

For testing, it is convenient to put the resources in the `public` folder and they will be served by the vite dev server.

For dashboard resources for `rmf_demos` simulation worlds, check out the [rmf-web-dashboard-resources](https://github.com/open-rmf/rmf_demos/tree/rmf-web-dashboard-resources) branch of `rmf_demos`.

### Micro-apps

The dashboard comes with many different micro-apps, each serving a different purpose when interacting with an Open-RMF deployment. The dashboard uses events to pipe information between micro-apps, for example clicking onto a task row in the Task app, will center the map onto the robot that the task was assigned to.

Here are the available apps,
Some of the built in MicroApps are:
* Robots
* Map
* Doors
Expand All @@ -54,39 +22,37 @@ Here are the available apps,
* Task Details
* Task Logs

### Workspace (tab) layouts
It is also possible to create new MicroApps, see [Creating a MicroApp](./docs/micro-apps.md#creating-a-microapp) for some examples.

Each workspace (tab) allows users to define how the layout of micro-apps should be. By modifying the `WorkspaceState` of the workspace, micro-apps can be resized, moved, added or removed.
## Workspaces

Here is an example workspace state,
A `Workspace` is a react component that render MicroApps based on a given layout, it makes it very easy to build a page in `rmf-dashboard-framework` by combining multiple MicroApps. Here is an example of a workspace

```typescript
export const robotsWorkspace: WorkspaceState = {
layout: [
{ i: 'robots', x: 0, y: 0, w: 7, h: 3 },
{ i: 'map', x: 8, y: 0, w: 5, h: 9 },
{ i: 'doors', x: 0, y: 0, w: 7, h: 3 },
{ i: 'lifts', x: 0, y: 0, w: 7, h: 3 },
{ i: 'beacons', x: 0, y: 0, w: 7, h: 3 },
{ i: 'mutexGroups', x: 8, y: 0, w: 5, h: 3 },
],
windows: [
{ key: 'robots', appName: 'Robots' },
{ key: 'map', appName: 'Map' },
{ key: 'doors', appName: 'Doors' },
{ key: 'lifts', appName: 'Lifts' },
{ key: 'beacons', appName: 'Beacons' },
{ key: 'mutexGroups', appName: 'Mutex Groups' },
],
};
```tsx
<Workspace initialWindows={[
{ layout: { x: 0, y: 0, w: 7, h: 8 }, microApp: tasksApp },
{ layout: { x: 8, y: 0, w: 5, h: 8 }, microApp: mapApp },
]} />
```

### Custom tab(s)

With the dashboard configuration parameter `customTabs: true`, 2 custom tabs would be available on the App bar. These custom tabs allow users to create a custom layout of desired micro-apps, if a custom workflow is desired.

These custom layouts will be cached locally on the browser's machine, where it can be brought up again.
The above workspace renders a "Tasks" and "Map" MicroApp with a fixed layout, but it supports a `designMode` that allows free customizable of the layout by the user at runtime

```tsx
<LocallyPersistentWorkspace
defaultWindows={[]}
allowDesignMode
appRegistry={[
mapApp,
doorsApp,
liftsApp,
robotsApp,
robotMutexGroupsApp,
tasksApp,
]}
storageKey="custom-workspace"
/>
```

To edit a custom tab, click onto the wand icon on the right end of the App bar, and proceed to add, resize, move or remove micro-apps from the layout.
## Examples

![](https://github.com/open-rmf/rmf-web/blob/media/custom-tabs.gif)
See [examples](./examples/)

0 comments on commit 2ff9f39

Please sign in to comment.