From ab07344068979701b12d3dc353be94a58d1cd6f6 Mon Sep 17 00:00:00 2001 From: CamDavidsonPilon Date: Thu, 4 Apr 2024 15:23:48 -0400 Subject: [PATCH] new docs --- developer-guide/20-User interface/02-api.md | 52 +++++++++++++------ .../01c-software-set-up.mdx | 10 +--- .../04-set-up-an-experiment.md | 15 ------ .../01-create-cluster.md | 35 +++++++------ user-guide/30-Advanced/01-cli.md | 9 ++-- 5 files changed, 61 insertions(+), 60 deletions(-) diff --git a/developer-guide/20-User interface/02-api.md b/developer-guide/20-User interface/02-api.md index b30f4df93..73a63b3c3 100644 --- a/developer-guide/20-User interface/02-api.md +++ b/developer-guide/20-User interface/02-api.md @@ -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/ get_available_calibrations_of_type GET /api/calibrations// -get_calibrations_of_type GET /api/calibrations/// +get_calibration_by_name GET /api/calibrations/// patch_calibrations PATCH /api/calibrations/// get_current_calibrations_of_type GET /api/calibrations///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/ delete_config DELETE /api/configs/ -update_new_config PATCH /api/configs/ +update_config PATCH /api/configs/ get_automation_contrib GET /api/contrib/automations/ 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/ +delete_experiment_profile DELETE /api/contrib/experiment_profiles/ get_job_contrib GET /api/contrib/jobs get_experiments GET /api/experiments create_experiment POST /api/experiments -update_experiment_description PATCH /api/experiments/ +update_experiment PATCH /api/experiments/ +get_logs GET /api/experiments//logs +get_media_rates GET /api/experiments//media_rates +get_unit_labels GET /api/experiments//unit_labels +upsert_unit_labels PUT /api/experiments//unit_labels +delete_experiment DELETE /api/experiments/ +get_list_of_workers_for_experiment GET /api/experiments//workers +add_worker_to_experiment PUT /api/experiments//workers +remove_workers_from_experiment DELETE /api/experiments//workers +remove_worker_from_experiment DELETE /api/experiments//workers/ +stop_all_in_experiment POST /api/experiments//workers/stop get_latest_experiment GET /api/experiments/latest export_datasets POST /api/export_datasets get_historical_config_for GET /api/historical_configs/ @@ -36,23 +51,30 @@ install_plugin POST /api/install_plugin get_installed_plugins GET /api/installed_plugins get_plugin GET /api/installed_plugins/ is_local_access_point_active GET /api/is_local_access_point_active -get_logs GET /api/logs/ -get_recent_logs GET /api/logs/recent -get_current_media_rates GET /api/media_rates/current reboot_unit POST /api/reboot/ -run_job_on_unit POST /api/run// -stop_job_on_unit POST /api/stop// -stop_all POST /api/stop_all +setup_worker_pioreactor POST /api/setup_worker_pioreactor +shutdown_unit POST /api/shutdown/ get_fallback_time_series GET /api/time_series/// get_growth_rates GET /api/time_series/growth_rates/ get_od_readings GET /api/time_series/od_readings/ get_od_readings_filtered GET /api/time_series/od_readings_filtered/ get_temperature_readings GET /api/time_series/temperature_readings/ -get_ui_version GET /api/ui_version uninstall_plugin POST /api/uninstall_plugin -get_current_unit_labels GET /api/unit_labels/ -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/ +get_worker GET /api/workers/ +get_experiment_assignment_for_worker GET /api/workers//experiment +change_worker_status PUT /api/workers//is_active +run_job_on_unit PATCH /api/workers//experiments//jobs//run +stop_job_on_unit PATCH /api/workers//jobs//stop +get_workers_and_experiment_assignments GET /api/workers/assignments static GET /static/ ``` diff --git a/user-guide/01-getting-started/01c-software-set-up.mdx b/user-guide/01-getting-started/01c-software-set-up.mdx index dd18d284e..06d2ed9b6 100644 --- a/user-guide/01-getting-started/01c-software-set-up.mdx +++ b/user-guide/01-getting-started/01c-software-set-up.mdx @@ -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)_ diff --git a/user-guide/02-Experiment basics/04-set-up-an-experiment.md b/user-guide/02-Experiment basics/04-set-up-an-experiment.md index 9c7ad2ef1..e9ef7dcd7 100644 --- a/user-guide/02-Experiment basics/04-set-up-an-experiment.md +++ b/user-guide/02-Experiment basics/04-set-up-an-experiment.md @@ -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 diff --git a/user-guide/03-Extending your Pioreactor/01-create-cluster.md b/user-guide/03-Extending your Pioreactor/01-create-cluster.md index 8d75c332d..b1e1929bd 100644 --- a/user-guide/03-Extending your Pioreactor/01-create-cluster.md +++ b/user-guide/03-Extending your Pioreactor/01-create-cluster.md @@ -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 @@ -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. \ No newline at end of file diff --git a/user-guide/30-Advanced/01-cli.md b/user-guide/30-Advanced/01-cli.md index 78f37b47e..679c36a2f 100644 --- a/user-guide/30-Advanced/01-cli.md +++ b/user-guide/30-Advanced/01-cli.md @@ -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 [...]` will safely terminate a ``. Can kill multiple jobs, ex: `pio kill stirring dosing_control` +* `pio kill --name --experiment ` or `pio kill --all-jobs` to end jobs. * `pio run ` will run the ``. 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. @@ -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 `: 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 `: 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 [...]` terminate the job `` on the workers. Ex: `pios kill dosing_control`. Multiple jobs can be killed, ex: `pios kill stirring dosing_control` +* `pios kill --name ` terminate the job `` on the workers. Ex: `pios kill --name dosing_control`. * `pios run ` on each worker, run the 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.