docs: v5 - Studio overview

docs/core/studio.md

@@ -7,12 +7,16 @@ import DocCardList from '@theme/DocCardList';
 # AICA Studio
 
 This section will give a brief, high-level tour of AICA Studio to help situate new users. Underlying concepts and
-examples will be covered in more depth in later sections of this documentation.
+examples are covered in more depth in later sections of this documentation.
+
+In short, AICA Studio is the graphical user interface layer to the AICA System to create, monitor and extend advanced
+robotic applications. It features an interactive application editor with a dataflow graph builder, a 3D scene visualizer
+and live data visualization. It also allows managing hardware configuration, user profiles and more.
 
 ## Application manager and editor
 
 The default landing page when opening AICA Studio is the application manager and editor. It can also be accessed by
-clicking the "Editor" tab in the top navbar.
+clicking the "Editor" link in the top navbar.
 
 It shows a list of saved applications and presents options to create a new application or upload applications from file.
 For a new installation with no saved applications, the list will be empty.
@@ -26,7 +30,7 @@ elements of which are described in the following subsections.
 
 ## Hardware manager
 
-The next top-level page is the hardware manager, available under the "Hardware" tab in the top navbar.
+The other top-level page is the hardware manager, available under the "Hardware" link in the top navbar.
 
 ![aica-studio-hardware-manager](./studio/assets/aica-studio-hardware-manager.png)
 
@@ -37,31 +41,28 @@ name.
 
 Any hardware listed in the hardware manager can be loaded and used in an application.
 
-## Docs
-
-Under the "Docs" tab in the top navbar, reference documentation for installed components and controllers in the AICA
-System configuration can be accessed.
+## Help
 
-![aica-studio-docs-page](./studio/assets/aica-studio-docs-page.png)
+The "Help" link in the top right section of the navbar is used to access a help page with links to documentation and
+learning resources.
 
-## Users
+![aica-studio-help-page](./studio/assets/aica-studio-help-page.png)
 
-The user icon in the top right of the page is used to access and manage the currently logged-in user profile.
+It also includes reference documentation for the installed components and controllers in the AICA System configuration.
 
-![aica-studio-user-page](./studio/assets/aica-studio-user-page.png)
+![aica-studio-docs-page](./studio/assets/aica-studio-docs-page.png)
 
-Read more about user scopes and API keys in [Users and authentication](/docs/getting-started/users-and-authentication).
+## Profile
 
-## Settings
+The "Profile" link in the top right of the page is used to access and manage the currently logged-in user profile.
 
-The settings page is accessed through the cogwheel icon on the top right of the page. It is only available to users with
-the `admin` scope and can be used to administer other users as well as connect to cloud storage and services.
+![aica-studio-profile-page](./studio/assets/aica-studio-profile-page.png)
 
-![aica-studio-settings-view](./studio/assets/aica-studio-settings-view.png)
+Read more about user scopes and API keys in [Profiles and scopes](./studio/profiles-and-scopes.md).
 
-## Logs
+## AICA Studio with Launcher
 
-Finally, the last button on the top right accesses the logs viewer. This page shows log entries from the running system
-and can be filtered and searched to find relevant entries.
+When using AICA Launcher v1.5.0 or newer with AICA Core v5.1.0 or newer, settings and controls related to AICA Launcher
+are available from the top right "Launcher" link in the navbar. This can be used to access 
 
-![aica-studio-logs-view](./studio/assets/aica-studio-logs-view.png)
+![aica-studio-launcher-settings](./studio/assets/aica-studio-launcher-settings.png)

docs/core/studio/3d.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 3
+title: 3D view
+---
+
+The 3D scene view shows hardware models and frames of the current application. When the application is running, the
+hardware positions and frames update live according to the active control logic.
+
+![aica-studio-3d-view](./assets/aica-studio-3d-view.png)
+
+The 3D view can be rotated by clicking and dragging within the scene, while holding right-click and dragging pans the
+view. Scroll over the view to zoom in or out. If the application defines any frames, they can be positioned and rotated
+by clicking and dragging on the frame markers.
+
+When the main view shows the 3D view, settings and controls for the 3D view can be accessed through the right panel
+Scene tab and Settings subtab. View settings control what is displayed in the 3D view, while additional controls allow
+creating or recording new application frames or joint positions from the current configuration.
+
+![aica-studio-3d-view-settings](./assets/aica-studio-3d-view-settings.png)
+
+When the main view shows the application graph, the 3D view can be accessed in the right panel under the 3D view tab.
+When this tab is selected, the mini-view is automatically minimized and 3D settings are accessed through an additional
+mini-panel from the Settings button.
+
+![aica-studio-3d-view-tab-settings](./assets/aica-studio-3d-view-tab-settings.png)
+

docs/core/studio/editor.md

@@ -9,32 +9,33 @@ When an application is created or selected for editing, the following applicatio
 
 ![aica-studio-application-editor](./assets/aica-studio-application-editor.png)
 
-On the left of the screen is the YAML code representation of the application, which is how applications are stored and
-parsed. On the right are visualization tools, including the unique application graph editor and the 3D scene viewer.
+The editor features two panels on the left and right side of a main view, with a mini-view in the bottom left. Next to
+the left panel is the main runtime control button. The Start button starts running the loaded application, which then
+changes into a Stop button to stop the running application.
 
-The white chevrons in the middle of the screen can be used to selectively expand the left or right portions of the
-screen.
+## Main view
 
-Application controls are shown above the YAML code.
+The main view shows the iconic AICA dataflow graph by default, which is explained more in the next section, while the
+mini-view shows a preview of 3D scene view. The left and right panels as well as the mini-view switcher can be minimized
+with the respective icon buttons to provide more screen space for the main view.
 
-Exit back to the application manager screen using the X button on the top left. It will prompt to save or discard
-unsaved changes. Running applications will be stopped when closing the application.
+The main view can also be switched to render the 3D scene of the application by clicking on the mini-view in the bottom
+left of the page. The mini-view will then correspondingly show the application graph instead of the 3D scene, and can
+be clicked again to switch the main view back to the application graph.
 
-Next to the X button, the cloud storage button can be used to upload and synchronize applications to cloud storage or
-downloaded them locally. This option is disabled until a user with `admin` scope connects to cloud storage in the
-[Settings](../studio.md#settings) page.
+## Left panel
 
-Applications can be deleted, saved, or saved as a copy under a new name.
+The left panel is used for managing application metadata with controls to rename, describe, and save the working
+version. Exit back to the application manager screen using the "Close" button in the left panel. When the left panel is
+minimized, the "X" button on the top left has the same function. Closing an application will prompt to save or discard
+unsaved changes. Running applications must be stopped before closing the application.
 
-The "Generate Graph" button is used to apply new code changes to the application graph. When editing the YAML code
-manually, changes will not take effect until this button is pressed.
+## Right panel
 
-The application can be renamed using the edit icon next to the application name. This also presents an option to add or
-edit the application description, which can serve as a way of differentiating and describing the purpose of various
-applications.
+The right panel is the context-aware data and property manager for actual application content and behavior grouped
+in various tabs. The width of the right panel can be adjusted with drag interactions to remain compact for normal usage
+or to take up more space for a split-screen effect with the main view. The right panel tabs contain the main tools for
+configuring and monitoring the application.
 
-In the top right of the application editor are the runtime controls. The Play button starts the loaded application,
-which can then be stopped with the Stop button.
-
-Beneath the runtime controls are the view selections for the various visualization tools, starting with the application
-graph. These views are presented in more detail in the next section.
+Read on to learn more about the [application graph editor](./graph.md), the [3D scene](./3d.md) and the
+[right panel tabs](./tab-views.md).

docs/core/studio/graph.md

@@ -39,20 +39,38 @@ the [concepts](/docs/category/application-building-blocks) section.
 
 ## Interacting with the graph
 
-Click and drag on the background of the graph or on the mini-map on the bottom left to pan the view and zoom in and out
-by scrolling. The graph control buttons next to the mini-map can also be used to zoom and fit the view.
+Click and drag on the background of the graph to pan the view and zoom in and out by scrolling.
 
-### Adding and deleting nodes
+### Adding elements to the graph
 
-Nodes can be added to the graph using the sidebar menu; press the (+) button in the top right corner of the graph to
-open the sidebar and see a list of available application elements. At the top of the list are the "Hardware Interface",
-"Trigger Events Button", "Sequence" and "Condition" nodes. These are followed by a list of all available components from
-AICA Core and any additionally installed packages, grouped by package. Clicking on any element in the sidebar will
-automatically add it to the graph.
+Application elements can be added to the graph using the right panel under the Scene tab and Add Component subtab:
 
-Nodes can be moved by clicking and dragging them. Depending on the type of node, clicking on various parts of the node
-will provide additional interaction options such as changing the display name, configuring parameters or expanding /
-collapsing certain fields.
+![aica-studio-add-component](./assets/aica-studio-add-component.png)
+
+At the top of the list are the "Hardware Interface", "Trigger Events Button", "Sequence" and "Condition" nodes. These
+are followed by a list of all available components from AICA Core and any additionally installed packages, grouped by
+package. Clicking on any element in the sidebar will automatically add it to the graph.
+
+The search field can be used to filter the available elements by name or description.
+
+### Managing graph elements
+
+Nodes can be moved by clicking and dragging them. When a node is selected, a small menu provides options to rename,
+duplicate or delete the node. Additionally, settings for the selected node will appear in the right panel under the
+Scene tab and Settings subtab. This is mainly used to configure automatic state transitions such as "auto-configure" or
+"auto-activate" and to set parameter values. The means of editing a parameter value depend on the parameter type, with
+simple toggles for boolean parameters, input fields for numeric and string parameters, and an input menu accessed
+through the pencil edit icon for array parameters.
+
+![aica-studio-component-settings](./assets/aica-studio-component-settings.png)
+
+Depending on the application element, clicking on various parts of the node will provide additional interaction options.
+In particular, components and hardware interfaces have toggleable badges to configure automatic state transitions
+without needing to open the Settings tab, while sequences have a toggle to enable looping behavior. Sections such as
+Transitions, Predicates and Services will have a Show All button that can be used to expand or collapse the respective
+interfaces.
+
+### Deleting graph elements
 
 To delete a node from the graph, press the small menu icon in its top right corner, then click Remove.
 
@@ -131,5 +149,3 @@ indicates which signals are actively transporting data with line animations and
 highlighting colors.
 
 ![aica-studio-application-graph-running](./assets/aica-studio-application-graph-running.png)
-
-Next, take a look at some of the other available application views.

docs/core/studio/profiles-and-scopes.md

@@ -0,0 +1,121 @@
+---
+sidebar_position: 5
+title: Profiles and scopes
+---
+
+The concept of "Profiles" in this section refers to creating distinct access credentials (or service accounts) for
+different operational purposes, such as for a monitoring dashboard with view-only permissions or an operator interface
+that can start and stop applications.
+
+:::note
+
+An AICA System License is a **single-user** license intended for one primary developer. The platform does not currently
+support live, simultaneous collaboration with other developers on the same system instance.
+
+:::
+
+Authentication prevents unauthorized users or software clients from accessing or controlling a running instance of the
+AICA System through AICA Studio or the API, even if they have access to the IP address and port of the AICA Core server.
+
+The user launching an AICA System configuration from AICA Launcher is treated as the system administrator rather than a
+regular profile, and must first switch to a regular profile to access AICA Studio.
+
+This section describes how to manage profiles with specific access scopes to explicitly authorize access to the running
+AICA System through a web browser or API client.
+
+:::info
+
+System administration privileges and API authentication are supported by AICA Launcher as of v1.2.0 and the Python API
+Client as of v3.1.0. Upgrade to the latest versions of these tools for full compatibility.
+
+:::
+
+## Scopes
+
+AICA Studio may have different or limited functionality depending on the scopes granted to the logged-in profile.
+Similarly, an API key with appropriate scopes is required to access respective endpoints and functionalities of the API.
+The available levels of scopes are described below.
+
+### `status`
+
+Read-only access to high-level information about the AICA System such as the available installed features. This is the
+minimum required scope.
+
+### `monitor`
+
+Read-only access to specific information about the AICA System such as configuration database entries or the state and
+live telemetry of running applications. Requires the `status` scope.
+
+### `control`
+
+Write-level access to edit applications, hardware entries and other configurations, and control-level access to set,
+start and manage running applications. Requires the `monitor` scope.
+
+### `users`
+
+Administration access to manage profiles (re-assigning scopes, resetting passwords, or deleting profiles) 
+
+### `cloud-configuration`
+
+Administration access to authorize and manage cloud service integrations.
+
+## Profiles
+
+When using AICA Launcher as the system administrator, AICA Studio will show a "Super Admin" landing page to select or
+manage the profile. Brand-new configurations will have no existing profiles.
+
+![aica-studio-super-admin-blank](assets/aica-studio-super-admin-blank.png)
+
+Profiles are created using an email address as the identifier and can be granted a combination of [scopes](#scopes).
+To edit and run applications in AICA Studio, the `control` scope is required.
+
+:::note
+
+The email address used to create a new profile is only used as an identifier and is unrelated to the email address used
+for [licensing](./installation/licensing). Profiles are defined locally to a specific AICA System Configuration, and
+access scopes or passwords are not inferred or shared between different configurations, even if the same email address
+is used.
+
+:::
+
+To create a new profile, click on the **New Profile** button in the Settings page, provide an email address and the
+desired scopes.
+
+![aica-studio-new-profile](assets/aica-studio-new-profile.png)
+
+A random password is generated for the newly created profile. It is only shown once, so it should be copied and stored for
+later use. If the password needs to be changed, first log out from the User page (or open AICA Studio in a new browser
+session), and log in as the new user with the generated password. Then, change the password in the User page by entering
+the generated (old) and the desired (new) password.
+
+![aica-studio-new-password](assets/aica-studio-new-password.png)
+
+:::tip
+
+If AICA Studio is accessed from a web browser, or if the user logs out of the current AICA Studio session, a valid
+profile email and password must be supplied to log in to AICA Studio.
+
+:::
+
+![aica-studio-login](assets/aica-studio-login.png)
+
+The [Profile](../studio.md#profile) page in AICA Studio can be used to view the current user with their available scopes, change the password or
+create API keys.
+
+## API Keys
+
+Other than accessing AICA Studio through a browser, users or software clients can interact with the AICA System using
+the API. In this case, an API key is required for authentication. This can be generated in the Profile page in
+AICA Studio, by clicking on the **New API Key** button. Provide a name and the desired scopes; note that these
+cannot surpass the scope of the logged-in user.
+
+Just as with the creation of new profiles, the newly created API key is shown once to be copied and saved in a secure
+place, as it cannot be accessed later. It can then be used it to authenticate and access AICA Core through the API.
+
+If an API key is lost or compromised, delete it from the Users page and generate a new one.
+
+:::tip
+
+Refer to our [API client documentation](https://pypi.org/project/aica-api/) for more info on the usage of API keys.
+
+:::