DOCS-1664/1666/1712/1677: Rework manage machines R2D2 (#2576)

docs/fleet/_index.md

@@ -56,9 +56,9 @@ For more information, see [Permissions](/fleet/rbac/#permissions).
 ### Configuration
 
 When you or your collaborators change the configuration of a machine or a group of machines in the Viam app, `viam-server` automatically synchronizes the configuration and updates the running resources within 15 seconds.
-This means everyone who has access can change a fleet's [configuration](machines/#configuration), even while your machines are running.
+This means everyone who has access can change a fleet's [configuration](machines/#configure), even while your machines are running.
 
-You can see configuration changes made by yourself or by your collaborators on the [History tab](machines/#history).
+You can see configuration changes made by yourself or by your collaborators by selecting **History** on the right side of your machine part's card on the **CONFIGURE** tab.
 You can also revert to an earlier configuration from the History tab.
 
 {{< alert title="Simultaneous config edits" color="caution" >}}
@@ -67,7 +67,7 @@ If you edit a config while someone else edits the same config, the person who sa
 Before editing a config, we recommend you refresh the page to ensure you have all the latest changes.
 {{< /alert >}}
 
-Machine [configuration](machines/#configuration) and machine [code](/build/program/) is intentionally kept separate, allowing you to keep track of versioning and debug issues separately.
+Machine [configuration](machines/#configure) and machine [code](/build/program/) is intentionally kept separate, allowing you to keep track of versioning and debug issues separately.
 
 ## The Viam mobile app
 

docs/fleet/machines.md

@@ -26,63 +26,57 @@ Click the name of a machine to go to that machine's page, where you'll find a va
 
 ## Navigating the machine page
 
-The banner at the top of the machine page displays the machine's location, name, and a dropdown list of all {{< glossary_tooltip term_id="part" text="parts" >}} of that machine.
+Next to the machine name, there is an indicator of the machine's status.
+Click on the **status** dropdown to open a menu with information about each {{< glossary_tooltip term_id="part" text="part" >}} of your machine.
+Once you connect to the `viam-server` instance on a part, this display includes its OS, Host, `viam-server` version, IP addresses, and what time it was last online or remote address (if live):
 
-If you've connected your physical machine running `viam-server` to its instance in the Viam app, the banner also displays when the machine was last online, which version of `viam-server` it is running, the host name, the IP address or addresses, and its operating system.
+![The machine page with part menu expanded](/fleet/app-usage/machine-page.png)
 
-![The machine page with menu tabs](/fleet/app-usage/machine-page.png)
+### Set up a new machine
 
-For each machine in your fleet, you start by setting up the machine on the **Setup** tab:
+<!-- TODO R2D2: might need screenshot and needs to be revisited once setup construction is finished -->
 
-### Setup
+To connect to the `viam-server` instance on a part, follow the setup instructions.
+Click **View setup instructions** on the part status dropdown menu in the top left corner.
 
-The **Setup** tab contains information for starting an instance of `viam-server` on your machine's computer.
-
-Once you select the correct **Architecture** for your system in the upper left of the tab, follow the instructions on the page to connect and set up your machine.
+Select your system's architecture and select the version of the {{< glossary_tooltip term_id="RDK" text="RDK" >}} to use.
+Then, follow the instructions on the page to connect and set up your machine.
 
 {{% alert title="Tip" color="tip" %}}
+The **Micro-RDK** is for [microcontrollers](/get-started/installation/prepare/microcontrollers/).
+
 More in-depth information on installing `viam-server` can be found in our [Install Guide](/get-started/installation/#install-viam-server).
 {{% /alert %}}
 
-### Configuration
+Once all parts of your machine are set up and connected to the app, the part status display at the top left corner of the page turns green.
+Now, you can manage your machine with one of four tabs: **CONFIGURE**, **CONTROL**, **LOGS**, and **CONNECT**:
+
+{{<imgproc src="/fleet/app-usage/parts-live.png" resize="400x" declaredimensions=true alt="The machine page with all parts live">}}
+
+### CONFIGURE
 
-When a machine or a {{< glossary_tooltip term_id="part" text="machine part" >}} that is managed with the Viam app first comes online, it requests its configuration from the [Viam app](https://app.viam.com).
+The configuration of a machine describes the {{< glossary_tooltip term_id="resource" text="resources" >}} that it has access to.
+When a {{< glossary_tooltip term_id="part" text="machine part" >}} that is managed with the Viam app first comes online, it requests its configuration from the [Viam app](https://app.viam.com).
 Once the machine has a configuration, it caches it locally and can use the configuration for up to 60 days.
 The machine checks for new configurations every 15 seconds and changes its configuration automatically when a new configuration is available.
 
-After connecting your machine, go to the **Config** tab, and start adding {{< glossary_tooltip term_id="component" text="components" >}}, {{< glossary_tooltip term_id="service" text="services" >}}, and other {{< glossary_tooltip term_id="resource" text="resources" >}}.
+After connecting your machine, go to the **CONFIGURE** tab, and start adding {{< glossary_tooltip term_id="component" text="components" >}}, {{< glossary_tooltip term_id="service" text="services" >}}, and other {{< glossary_tooltip term_id="resource" text="resources" >}}.
+
+<!-- TODO R2D2: need to check that this works once page is set up -->
+
+To see the history of the configuration of a machine part, click on **History** on the right side of its card on the **CONFIGURE** tab.
 
 For more information, see the [configuration documentation](/build/configure/#the-config-tab).
 
 {{< alert title="Tip" color="tip" >}}
 If you are managing a large fleet, you can use {{< glossary_tooltip term_id="fragment" text="fragments" >}} when [configuring your machine](/build/configure/).
 {{< /alert >}}
 
-### History
-
-The configuration of your machine and the code it runs are kept separate to make debugging easier.
-The **History** tab shows timestamped changes to your machine's configuration.
-
-If you want to revert changes that you made, you can load a previous configuration by clicking the **Load config** button next to the respective configuration.
-
-{{<gif webm_src="/manage/load-prev-config.webm" mp4_src="/manage/load-prev-config.mp4" alt="Load a previous config from the UI" max-width="800px">}}
-
-You can also change your timestamp format to ISO or Local depending on your preference.
-
-### Logs
-
-To make debugging issues with your machines easier, each machine automatically sends its logs to the cloud.
-You can access your logs from the **Logs** tab in the [Viam app](https://app.viam.com) and filter your logs for specific keywords or log levels:
-
-{{<gif webm_src="/manage/log-filtering.webm" mp4_src="/manage/log-filtering.mp4" alt="Filter logs by term of log level in the UI" max-width="800px">}}
-
-You can also change your timestamp format to ISO or Local depending on your preference.
-
-### Control
+### CONTROL
 
-Once you have configured components and services for your machine, you can visually test and remotely operate them from the **Control** tab in the [Viam app](https://app.viam.com).
+Once you have configured components and services for your machine, you can visually test and remotely operate them from the **CONTROL** tab in the [Viam app](https://app.viam.com).
 For example, if you have configured a base with wheels, you can control your machine's movement with an arrow pad and fields to change base’s speed.
-If you have configured a camera component, a window in the **Control** tab displays the camera output.
+If you have configured a camera component, a window in the **CONTROL** tab displays the camera output.
 
 If you use remote control in the [Viam app](https://app.viam.com) UI, all communication to the machine uses [WebRTC](https://pkg.go.dev/go.viam.com/[email protected]/rpc#hdr-Connection).
 For local communication between [parts](/build/configure/parts-and-remotes/#machine-parts) Viam uses gRPC or WebRTC.
@@ -93,30 +87,45 @@ For local communication between [parts](/build/configure/parts-and-remotes/#mach
 
 You can also access the control interface using the [Viam mobile app](/fleet/#the-viam-mobile-app), which you can find on the [App Store](https://apps.apple.com/vn/app/viam-robotics/id6451424162) and on [Google Play](https://play.google.com/store/apps/details?id=com.viam.viammobile&hl=en&gl=US).
 
-### Code Sample
+### LOGS
 
-To start programming your machine, go to the **Code sample** tab which contains boilerplate code snippets you can copy and paste into your SDK code to connect to your machine.
+To make debugging issues with your machines easier, each machine automatically sends its logs to the cloud.
+You can access your logs from the **LOGS** tab in the [Viam app](https://app.viam.com) and filter your logs for specific keywords or log levels:
+
+{{<gif webm_src="/manage/log-filtering.webm" mp4_src="/manage/log-filtering.mp4" alt="Filter logs by term of log level in the UI" max-width="800px">}}
+
+You can click on the part names in the left-hand menu to switch logs between parts. You can also change your timestamp format to ISO or Local depending on your preference.
+
+### CONNECT
+
+#### Code sample
+
+To start programming your machine, go to the **CONNECT** tab and select the **Code sample** page.
+This has boilerplate code snippets you can copy and paste into your SDK code to connect to your machine.
 
 {{% snippet "show-secret.md" %}}
 
 For more information on the SDKs, see [Program your Machine with Viam's SDKs](/build/program/apis/).
 
-There is also a JSON stub you can copy if you wish to have your machine communicate with another machine as a [remote](/build/configure/parts-and-remotes/).
+#### Configure as remote part
 
-### Security
+On the **CONNECT** tab, there is also a page called **Configure as remote part**.
+This page has instructions for how to configure a {{< glossary_tooltip term_id="part" text="part" >}} of your machine as a [remote part](/build/configure/parts-and-remotes/) of another machine.
 
-Your machine and the Viam app communicate securely using [WebRTC](https://pkg.go.dev/go.viam.com/[email protected]/rpc#hdr-Connection) with unique secrets.
+#### API keys
 
-The **Security** tab allows you to access, generate, and delete the **Machine part secret keys** and the **Machine part API keys** of your machine.
+Your machine and the Viam app communicate securely using [WebRTC](https://pkg.go.dev/go.viam.com/[email protected]/rpc#hdr-Connection) with unique secrets.
+The **API keys** page of the **CONNECT** tab allows you to access, generate, and delete your [API keys](/fleet/rbac/#api-keys), which grant access to organizations, locations, and machines.
 
 ![The Security tab of a machine's page noting the Machine part API keys dropdown menu, with the clipboard icon on the far right and the Generate Key button underneath the dropdown.](/fleet/app-usage/machine-secrets.png)
 
-You can copy a secret by clicking on the clipboard icon.
+Copy an API key or API key ID by clicking on the clipboard icon.
+Click **Show details** and **Access settings** to go to your organization settings page, where you can modify the access your API keys provide.
 
 {{% snippet "secret-share.md" %}}
 
 ## Delete a machine
 
-You can delete a machine by navigating to its page in [the Viam app](https://app.viam.com) and selecting **Sure?** and **Delete machine** in the lower left corner of the page.
+Delete a machine by clicking on the **...** menu in the top right hand corner of its page, selecting **Delete machine**, and confirming that you're sure.
 
 {{< imgproc alt="The delete machine button and the confirmation checkbox (Sure?) next to it." src="/fleet/app-usage/delete.png" resize="300x" >}}

docs/fleet/rbac.md

@@ -14,7 +14,7 @@ Users can have access to different fleet management capabilities depending on wh
 - **Owner**: Can see and edit [every tab on the machine page](/fleet/machines/#navigating-the-machine-page).
   Can manage users in the app.
 - **Operator**: Can see and use only the [**CONTROL**](/fleet/machines/#control) tab.
-  Cannot see or edit the [**CONFIGURE**](/fleet/machines/#configuration), [**LOGS**](/fleet/machines/#logs), or **CONNECT** tabs.
+  Cannot see or edit the [**CONFIGURE**](/fleet/machines/#configure), [**LOGS**](/fleet/machines/#logs), or **CONNECT** tabs.
 
 For more detailed information on the permissions each role confers for different resources, see [Permissions](/fleet/rbac/#permissions).
 

docs/get-started/viam.md

@@ -70,7 +70,7 @@ For each component that makes up your machine:
 
 1. Add it to your machine by [choosing the component type](/build/configure/#components) (example: `camera`) and model (example: `webcam`).
 2. Test it with the visual [control tab](/fleet/machines/#control).
-3. See any problems with in-app [logs](/fleet/machines/#logs), review or roll back configuration [history](/fleet/machines/#history).
+3. See any problems with in-app [logs](/fleet/machines/#logs), review or roll back [configuration history](/fleet/machines/#configure).
 
 After configuring your machine's hardware, you can configure [high level functionality](/services/) the same way:
 

docs/internals/rdk.md

@@ -45,7 +45,7 @@ After start-up, `viam-server` manages:
 When you or your collaborators change the configuration of a machine in the Viam app, `viam-server` automatically synchronizes the configuration to your machine and updates the running resources within 15 seconds.
 This means you can add, modify, and remove a modular resource instance from a running machine.
 
-You can see configuration changes made by yourself or by your collaborators on the [History tab](/fleet/machines/#history).
+You can see configuration changes made by yourself or by your collaborators by selecting **History** on the right side of your machine part's card on the **CONFIGURE** tab.
 You can also revert to an earlier configuration from the History tab.
 
 ### Logging

static/include/program/authenticate.md

@@ -4,7 +4,7 @@ To authenticate yourself to your machine, you need
 
       <!-- we will be releasing the ability to create API keys across all types of resources and combinations soon (i.e an API key can have an authorization on a org, location, machine or any combination of all three). this is correct for now though but it will be changing shortly. -->
 
-   To authenticate, [use a machine part API key](/fleet/machines/#security) or [an API key](/fleet/cli/#authenticate) with access to the machine.
+   To authenticate, [use a machine part API key](/fleet/machines/#api-keys) or [an API key](/fleet/cli/#authenticate) with access to the machine.
    Copy and paste the API key ID and the API key into your environment variables or directly into the code:
 
    {{< tabs >}}