[[Include(WikiToC)]]
= COSMOS Portal User Guide =

The [https://www.cosmos-lab.org/portal COSMOS Portal] is a web application for managing your testbed account, making reservations, and monitoring testbed resources. This guide covers the features available to regular users.

The portal is accessible at '''https://www.cosmos-lab.org/portal'''

== Getting Started == #GettingStarted

=== Creating an Account ===

1. Go to [https://www.cosmos-lab.org/register_usr Register User]
2. Fill in your details:
   * '''Username''' -- 3-16 characters, lowercase letters, digits, and underscores (must start with a letter)
   * '''Name, Email, Phone''' -- your contact information
   * '''Organization''' -- select your research group from the dropdown (search to filter)
   * '''Password''' -- must be at least 8 characters with uppercase, lowercase, digit, and special character
   * '''Mailing List''' -- choose Full, Digest, or None
3. You will receive a confirmation email -- click the link within 30 minutes to complete your request
4. Your group PI will approve your request
5. You will receive a final confirmation email once approved

[[Image(portal-register.png, width=60%)]]

If your organization is not listed and you are a faculty/staff member, ask your PI to [https://www.cosmos-lab.org/register_org register a new organization] first.

=== Logging In ===

1. Go to [https://www.cosmos-lab.org/portal/login Portal Login]
2. Enter your username and password
3. You will be taken to the Dashboard

[[Image(portal-login.png, width=40%)]]

If you forgot your username or password, use the links on the login page to recover them via email.

== Dashboard == #Dashboard

The Dashboard is your home page after logging in. It shows:

* '''Profile card''' -- your name, username, email, organization, and member-since date
* '''Quick links''' -- Edit Profile and SSH Keys
* '''Usage statistics''':
  * '''Disk Usage''' -- total storage used across all paths
  * '''Reservations''' -- total reservation count (all-time and last 4 weeks)
  * '''Login Time''' -- total session time and session count

[[Image(portal-dashboard.png, width=80%)]]

== Account Management == #Account

=== Edit Profile ===

Click your name in the top-right corner and select '''Edit Profile''', or navigate to the Dashboard and click the Edit Profile link.

You can update:
* First and last name
* Email address
* Phone number

[[Image(portal-profile.png, width=60%)]]

=== Change Password ===

On the Edit Profile page, scroll down to the Change Password section:
1. Enter your current password
2. Enter and confirm your new password
3. Click Save

=== SSH Keys ===

Click your name in the top-right corner and select '''SSH Keys''' to manage your public keys for console access.

* '''Upload a key''' -- paste your public key (supports ssh-rsa, ssh-ed25519, ecdsa, and other standard formats). The key is validated in real-time before upload.
* '''View keys''' -- see all uploaded keys with their type and comment
* '''Delete a key''' -- remove individual keys you no longer need

You can upload multiple keys. These are used for SSH access to testbed consoles during your reservations.

[[Image(portal-ssh-keys.png, width=60%)]]

== Scheduler == #Scheduler

The Scheduler lets you reserve testbed resources (domains/sandboxes) for your experiments.

=== Viewing the Calendar ===

Navigate to '''Scheduler''' in the left sidebar. The calendar shows:
* '''Day''' or '''Week''' view (toggle at the top)
* Resources listed on the left, time slots across the top
* Date navigation with Previous/Next/Today buttons and a date picker
* Time is shown in your local timezone, with UTC and COSMOS Eastern Time displayed

[[Image(portal-scheduler.png, width=80%)]]

=== Reservation Colors ===

||= Color =||= Meaning =||
|| Green (solid) || Your approved reservation ||
|| Light green || Your pending reservation ||
|| Blue || Another user's approved reservation ||
|| Yellow || Another user's pending reservation ||
|| Red || Conflict (overlapping pending reservations) ||
|| Gray/Orange || Blackout/maintenance period ||

=== Creating a Reservation ===

1. Click on an empty time slot in the calendar
2. In the dialog, configure:
   * '''Start and end time''' -- select your desired time window
   * '''Summary''' (optional) -- a short description of your experiment
   * '''Participants''' (optional) -- search and add other users who should have access
   * '''Group reservation''' (optional) -- select a group to grant access to all members
   * '''Recurrence''' (optional) -- set up weekly or monthly recurring reservations with an end date
3. Click '''Submit''' -- your reservation appears as pending (light green or yellow)

Reservations are approved automatically:
* Requests made before noon are pre-approved for the following day by 2 PM
* Other requests are approved at the start of the time slot (just-in-time)

=== Competing for a Slot ===

If another user has a pending reservation on a slot you want, you can click that slot and select '''Compete for this slot'''. The system resolves conflicts based on usage -- users who have used less testbed time in the last two weeks are given priority. Avoid competing for slots less than 2 hours in the future.

=== Modifying or Canceling ===

* Click on your reservation to view its details
* '''Edit''' -- change the time, duration, or summary
* '''Cancel''' -- remove a pending or approved reservation
* '''Delete Series''' -- cancel all future occurrences of a recurring reservation

=== My Reservations ===

Navigate to '''My Reservations''' in the sidebar to see:
* Your usage statistics (total hours in the last 28 days)
* A table of all upcoming reservations with resource, time, duration, and status
* A cancel button for each reservation

[[Image(portal-my-reservations.png, width=80%)]]

== Status Pages == #Status

Status pages appear in the sidebar '''only when you have an active or upcoming reservation''' (within 24 hours).

=== Node Status ===

Shows the power state of all testbed nodes as a visual grid. This page is visible when you have any reservation.

=== RF Matrix ===

Shows the RF attenuation matrix for sandbox SB4. This page is visible only when you have an SB4 reservation.

Features:
* Visual network topology graph showing connections between ports and devices
* Click on connections to set attenuation values (0-63 dB)
* Toggle WiFi/SDR mode for each port
* '''Reset All''' -- set all attenuations to 0 dB and WiFi mode
* '''Save/Load configurations''' -- save your current matrix setup for reuse (public or private)
* Configurations auto-refresh every 5 seconds

== Directory == #Directory

=== Users ===

Navigate to '''Users''' in the sidebar to browse all registered users.
* Filter by letter (A-Z) or search by name/username
* Sortable columns: Username, Name, Email, Group, Created date
* Paginated results (20 per page)


=== Groups ===

Navigate to '''Groups''' to browse all organizations.
* Filter by letter or search
* Click a group name to view its details: members list, PI(s), and subgroups


== Navigation Reference == #Navigation

The portal sidebar shows the following sections for regular users:

||= Section =||= Pages =||= Description =||
|| My Account || Dashboard || Profile summary and usage stats ||
|| Scheduler || Scheduler || Calendar view for reservations ||
|| || My Reservations || List of your upcoming reservations ||
|| Status || Node Status || Testbed node power states (when you have a reservation) ||
|| || RF Matrix - SB4 || RF attenuation matrix (when you have an SB4 reservation) ||
|| Directory || Users || Browse all registered users ||
|| || Groups || Browse all organizations ||

The top-right user menu provides quick access to '''Edit Profile''', '''SSH Keys''', and '''Log Out'''.

== Tips == #Tips

* '''Mobile friendly''' -- on small screens, the sidebar becomes a hamburger menu
* '''Hover for help''' -- each sidebar link has an info icon with a tooltip describing the page
* '''Keyboard shortcuts''' -- press Escape to close dialogs
* '''Timezone awareness''' -- the scheduler always shows times in your local timezone with UTC reference