Skip to content

Commit

Permalink
new docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@CamDavidsonPilon
CamDavidsonPilon committed Apr 4, 2024
1 parent 13dfda4 commit ab07344
Show file tree
Hide file tree
Showing 5 changed files with 61 additions and 60 deletions.
52 changes: 37 additions & 15 deletions developer-guide/20-User interface/02-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,24 +9,39 @@ slug: /web-ui-api
```
Endpoint Methods Rule
--------------------------------------- ------- -------------------------------------------------------------------------
add_new_pioreactor POST /api/add_new_pioreactor
get_app_version GET /api/app_version
create_new_calibrations PUT /api/calibrations
able_to_install_plugins_from_ui GET /api/alllow_ui_installs
create_or_update_new_calibrations PUT /api/calibrations
get_available_calibrations_type_by_unit GET /api/calibrations/<pioreactor_unit>
get_available_calibrations_of_type GET /api/calibrations/<pioreactor_unit>/<calibration_type>
get_calibrations_of_type GET /api/calibrations/<pioreactor_unit>/<calibration_type>/<calibration_name>
get_calibration_by_name GET /api/calibrations/<pioreactor_unit>/<calibration_type>/<calibration_name>
patch_calibrations PATCH /api/calibrations/<pioreactor_unit>/<calibration_type>/<calibration_name>
get_current_calibrations_of_type GET /api/calibrations/<pioreactor_unit>/<calibration_type>/current
get_custer_time GET /api/cluster_time
set_cluster_time POST /api/cluster_time
get_configs GET /api/configs
get_config GET /api/configs/<filename>
delete_config DELETE /api/configs/<filename>
update_new_config PATCH /api/configs/<filename>
update_config PATCH /api/configs/<filename>
get_automation_contrib GET /api/contrib/automations/<automation_type>
get_charts_contrib GET /api/contrib/charts
create_experiment_profile POST /api/contrib/experiment_profiles
get_experiment_profiles GET /api/contrib/experiment_profiles
get_experiment_profile GET /api/contrib/experiment_profiles/<filename>
delete_experiment_profile DELETE /api/contrib/experiment_profiles/<filename>
get_job_contrib GET /api/contrib/jobs
get_experiments GET /api/experiments
create_experiment POST /api/experiments
update_experiment_description PATCH /api/experiments/<experiment>
update_experiment PATCH /api/experiments/<experiment>
get_logs GET /api/experiments/<experiment>/logs
get_media_rates GET /api/experiments/<experiment>/media_rates
get_unit_labels GET /api/experiments/<experiment>/unit_labels
upsert_unit_labels PUT /api/experiments/<experiment>/unit_labels
delete_experiment DELETE /api/experiments/<experiment_id>
get_list_of_workers_for_experiment GET /api/experiments/<experiment_id>/workers
add_worker_to_experiment PUT /api/experiments/<experiment_id>/workers
remove_workers_from_experiment DELETE /api/experiments/<experiment_id>/workers
remove_worker_from_experiment DELETE /api/experiments/<experiment_id>/workers/<pioreactor_unit>
stop_all_in_experiment POST /api/experiments/<experiment_id>/workers/stop
get_latest_experiment GET /api/experiments/latest
export_datasets POST /api/export_datasets
get_historical_config_for GET /api/historical_configs/<filename>
Expand All @@ -36,23 +51,30 @@ install_plugin POST /api/install_plugin
get_installed_plugins GET /api/installed_plugins
get_plugin GET /api/installed_plugins/<filename>
is_local_access_point_active GET /api/is_local_access_point_active
get_logs GET /api/logs/<experiment>
get_recent_logs GET /api/logs/recent
get_current_media_rates GET /api/media_rates/current
reboot_unit POST /api/reboot/<unit>
run_job_on_unit POST /api/run/<unit>/<job>
stop_job_on_unit POST /api/stop/<unit>/<job>
stop_all POST /api/stop_all
setup_worker_pioreactor POST /api/setup_worker_pioreactor
shutdown_unit POST /api/shutdown/<unit>
get_fallback_time_series GET /api/time_series/<data_source>/<experiment>/<column>
get_growth_rates GET /api/time_series/growth_rates/<experiment>
get_od_readings GET /api/time_series/od_readings/<experiment>
get_od_readings_filtered GET /api/time_series/od_readings_filtered/<experiment>
get_temperature_readings GET /api/time_series/temperature_readings/<experiment>
get_ui_version GET /api/ui_version
uninstall_plugin POST /api/uninstall_plugin
get_current_unit_labels GET /api/unit_labels/<experiment>
upsert_current_unit_labels PUT /api/unit_labels/current
update_app POST /api/update_app
update_app_from_release_archive POST /api/update_app_from_release_archive
update_app_to_develop POST /api/update_app_to_develop
upload POST /api/upload
get_app_version GET /api/versions/app
get_ui_version GET /api/versions/ui
get_list_of_workers GET /api/workers
add_worker PUT /api/workers
delete_worker DELETE /api/workers/<pioreactor_unit>
get_worker GET /api/workers/<pioreactor_unit>
get_experiment_assignment_for_worker GET /api/workers/<pioreactor_unit>/experiment
change_worker_status PUT /api/workers/<pioreactor_unit>/is_active
run_job_on_unit PATCH /api/workers/<unit>/experiments/<experiment>/jobs/<job>/run
stop_job_on_unit PATCH /api/workers/<unit>/jobs/<job>/stop
get_workers_and_experiment_assignments GET /api/workers/assignments
static GET /static/<path:filename>
```

Expand Down
10 changes: 1 addition & 9 deletions user-guide/01-getting-started/01c-software-set-up.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,15 +117,7 @@ Workers are additional Pioreactors that you can control from a single UI. Togeth

#### Step 2. Add worker to cluster using the UI

On the _Pioreactors_ page in the web interface, click the "Add new Pioreactor" button in the top right:

![Add new pioreactor](/img/user-guide/add_new_pioreactor.png)

Provide the chosen hostname of the new worker Pioreactor:

![Add new pioreactor modal](/img/user-guide/add_new_pioreactor_modal.png)

After a minute, the worker's blue LED will turn off, and the new Pioreactor should appear on the _Pioreactors_ and _Experiment Overview_ page. Refresh the page if it does not show up. Your new worker Pioreactor will also blink its blue LED telling you it's online.
Follow the instructions [here to add your worker to your Pioreactor cluster](/user-guide/create-cluster#adding-pioreactors-to-your-cluster).


#### From the command line _(Alternative)_
Expand Down
15 changes: 0 additions & 15 deletions user-guide/02-Experiment basics/04-set-up-an-experiment.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,6 @@ import Admonition from '@theme/Admonition';

![](/img/user-guide/create_new_experiment_page.png)

### Adding Pioreactors to your inventory

In the _Inventory_ tab, you can search for and add worker Pioreactors to your cluster. Click "Add new Pioreactor" at the top right corner of this tab.

![](/img/user-guide/inventory-tab.png)

In the popup, search for the name of your worker and click "Add Pioreactor".

![](/img/user-guide/add-new-pioreactor.png)

Once a new Pioreactor is added, you will need to refresh the page to see the new worker in the cluster.

This Inventory tab will display metadata pertaining to each of your Pioreactors. You can use this page to identify a Pioreactor (causes the blue LED on the HAT to blink), unassign a Pioreactor from any experiment, reboot a Pioreactor, or remove it from your cluster. This page also provides a summary of which Pioreactors are assigned to which experiment, as highlighted in yellow in the image below.

![](/img/user-guide/inventory-multiple-pios.png)

### Assigning Pioreactors to your experiment

Expand Down
35 changes: 18 additions & 17 deletions user-guide/03-Extending your Pioreactor/01-create-cluster.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,34 @@ title: Creating a Pioreactor cluster
slug: /create-cluster
---

Pioreactors are able to be used as individual units, or in concert with other Pioreactors. In either case, a Pioreactor needs to be assigned as a _leader_. The leader unit controls other Pioreactors (and that may include itself), stores the database, hosts the web interface, and is the interface between users and the hardware.
Pioreactors are able to be used as individual units, or in concert with other Pioreactors. In either case, a Pioreactor needs to be assigned as a _leader_. The leader unit controls other Pioreactors (and that may include itself), stores the database, hosts the web interface, and is the interface between users and the hardware. A leader will communicate and control all the _workers_ (non-leader Pioreactors) in the _inventory_.

:::info
When you set up your first Pioreactor using our [software installation guide](/user-guide/software-set-up), your Pioreactor was set up to be a leader already. You only need one leader in a Pioreactor cluster.
:::


A leader will communicate and control all the _workers_ (non-leader Pioreactors) in the _inventory_. The inventory is a list of workers in your cluster, defined in the section `cluster.inventory` in the `config.ini`.
### Adding Pioreactors to your cluster

![](https://user-images.githubusercontent.com/884032/103158311-5316e380-478a-11eb-9425-6bb0df079d58.png)
After installing the worker image onto your additional Pioreactor (see the instructions [here](/user-guide/software-set-up#adding-additional-workers-to-your-cluster)), visit the Inventory page.

On the _Inventory_ page, you can search for and add worker Pioreactors to your cluster. Click "Add new Pioreactor" at the top right corner of this tab.

Workers can be *active* (available for running activities and housing cultures), or inactive. This is set with `1` or `0` respectively in the `cluster.inventory` section.
![](/img/user-guide/inventory-tab.png)

When you want to remove a Pioreactor from your cluster, you can remove it from the list in available inventory in `cluster.inventory` section in `config.ini`.
In the popup, add the name of your worker and click "Add Pioreactor".

![](/img/user-guide/add-new-pioreactor.png)

Once a new Pioreactor is added, you may need to refresh the page to see the new worker in the cluster.

This Inventory tab will display metadata pertaining to each of your Pioreactors. You can use this page to identify a Pioreactor (causes the blue LED on the HAT to blink), unassign a Pioreactor from any experiment, reboot a Pioreactor, or remove it from your cluster. This page also provides a summary of which Pioreactors are assigned to which experiment, as highlighted in yellow in the image below.

![](/img/user-guide/inventory-multiple-pios.png)



Workers can be *active* (available for running activities and cultures), or inactive. Inactive Pioreactors can still be assigned to experiments, but won't response to commands to run activities or participate in experiment profiles.


### Possible cluster topologies
Expand All @@ -44,16 +57,4 @@ You can also choose not to have the leader be a worker. This is useful if you ha

![leader not worker](/img/user-guide/leader_cluster.png)

### How to edit roles

To tell the cluster which computer is the leader, you edit the `config.ini`'s `leader_hostname` section (under `cluster.topology`):

![where to edit the leader](https://user-images.githubusercontent.com/884032/103158348-b43eb700-478a-11eb-80d9-883458107f31.png)

Inventory is assigned in `config.ini` under `cluster.inventory`:

![](https://user-images.githubusercontent.com/884032/103158311-5316e380-478a-11eb-9425-6bb0df079d58.png)

### Adding new workers

See the instructions [here](/user-guide/software-set-up#adding-workers-to-your-cluster) to add new workers to your cluster.
9 changes: 5 additions & 4 deletions user-guide/30-Advanced/01-cli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ For those interested, you can use the command line to interact with the Pioreact
Interacting with the Pioreactor on the command line are through the `pio` tool. Available arguments are:

* `pio logs` will produce a stream of recent logs events. Logs are stored in `/var/log/pioreactor.log`.
* `pio kill <job> [<job>...]` will safely terminate a `<job>`. Can kill multiple jobs, ex: `pio kill stirring dosing_control`
* `pio kill --name <job> --experiment <exp>` or `pio kill --all-jobs` to end jobs.
* `pio run <job> <options>` will run the `<job>`. Each job may have specific command line arguments.
* `pio version` print the version of the PioreactorApp software.
* `pio update app` will update the software to the latest app version.
Expand All @@ -29,17 +29,18 @@ The leader also has their own unique set of `pio` commands (these commands do no

* `pio db`: open the sqlite3 CLI of the Pioreactor database.
* `pio mqtt`: tail the MQTT broker.
* `pio add-pioreactor <hostname>`: add a Pioreactor to your cluster, with given (unique) name. Need a worker Pioreactor on the network first. See instructions [here](https://github.com/Pioreactor/pioreactor/wiki/Installation).
* `pio update ui` will update the UI software to the latest version and adding `--app` will upgrade the Pioreactor Python app (repo: pioreactor/pioreactor).
* `pio update app` will update the software to the latest version.
* `pio cluster-status` will report to the user each Pioreactor in the cluster, and metadata like status, IP, and state.
* `pio discover-workers` will return a list of workers on the network (may be a superset of the current cluster.)
* `pio workers` has many subcommands for manager your cluster. For example:
* `pio workers add <hostname>`: add a Pioreactor to your cluster, with given (unique) name. Need a worker Pioreactor on the network first. See instructions [here](https://github.com/Pioreactor/pioreactor/wiki/Installation).
* `pio workers discover` will return a list of workers on the network (may be a superset of the current cluster.)

#### Leader-only commands to control workers

The leader computer interacts with the worker computers using the `pios` command. Unless otherwise noted, the `pios` will target all worker computers. Available `pios` commands on the leader computer are the following:

* `pios kill <job> [<job>...]` terminate the job `<job>` on the workers. Ex: `pios kill dosing_control`. Multiple jobs can be killed, ex: `pios kill stirring dosing_control`
* `pios kill --name <job>` terminate the job `<job>` on the workers. Ex: `pios kill --name dosing_control`.
* `pios run <job>` on each worker, run the job `<job>` in the background. Job specific arguments can be specified after. Ex: `pios run add_media --ml 1`. Use `-y` to skip confirmation.
* `pios update` install the latest PioreactorApp code on each worker.
* `pios sync-configs` deploy the config.ini files to workers.
Expand Down

0 comments on commit ab07344

Please sign in to comment.