diff --git a/developer-guide/20-User interface/02-api.md b/developer-guide/20-User interface/02-api.md index 268e8ff7..83cd1937 100644 --- a/developer-guide/20-User interface/02-api.md +++ b/developer-guide/20-User interface/02-api.md @@ -6,104 +6,113 @@ slug: /web-ui-api ### All endpoints ``` -Endpoint Methods Rule ---------------------------------------- ----------- ---------------------------------------------------------------------------------- -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_calibration_by_name GET /api/calibrations/// -patch_calibrations PATCH /api/calibrations/// -get_current_calibrations_of_type GET /api/calibrations///current -get_configs GET /api/configs -get_config GET /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 -update_experiment_profile PATCH /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 -delete_experiment DELETE /api/experiments/ -update_experiment PATCH /api/experiments/ -get_experiment GET /api/experiments/ -get_logs GET /api/experiments//logs -get_media_rates GET /api/experiments//media_rates -get_fallback_time_series GET /api/experiments//time_series// -get_growth_rates GET /api/experiments//time_series/growth_rates -get_od_readings GET /api/experiments//time_series/od_readings -get_od_readings_filtered GET /api/experiments//time_series/od_readings_filtered -get_temperature_readings GET /api/experiments//time_series/temperature_readings -get_unit_labels GET /api/experiments//unit_labels -upsert_unit_labels PATCH, PUT /api/experiments//unit_labels -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/ -get_experiments_worker_assignments GET /api/experiments/assignment_count -get_latest_experiment GET /api/experiments/latest -export_datasets POST /api/export_datasets -get_historical_config_for GET /api/historical_configs/ -get_historical_media_used GET /api/historical_media -get_historical_organisms_used GET /api/historical_organisms -is_local_access_point_active GET /api/is_local_access_point_active -get_jobs_running_across_cluster GET /api/jobs/running -install_plugin_across_cluster PATCH, POST /api/plugins/install -get_plugins_across_cluster GET /api/plugins/installed -uninstall_plugin_across_cluster PATCH, POST /api/plugins/uninstall -upload POST /api/system/upload -run_job_on_unit_in_experiment PATCH, POST /api/units//jobs/run/job_name//experiments/ -get_running_jobs_on_unit GET /api/units//jobs/running -stop_job_on_unit PATCH, POST /api/units//jobs/stop/job_name//experiments/ -update_job_on_unit PATCH /api/units//jobs/update/job_name//experiments/ -reboot_unit POST /api/units//system/reboot -shutdown_unit POST /api/units//system/shutdown -update_app POST /api/update_app -update_app_from_release_archive POST /api/update_app_from_release_archive -get_app_versions_across_cluster GET /api/versions/app -get_ui_versions_across_cluster 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 -get_logs_for_unit_and_experiment GET /api/workers//experiments//logs -change_worker_status PUT /api/workers//is_active -run_job_on_unit_in_experiment PATCH, POST /api/workers//jobs/run/job_name//experiments/ -get_running_jobs_on_unit GET /api/workers//jobs/running -stop_all_jobs_on_worker_for_experiment PATCH, POST /api/workers//jobs/stop/experiments/ -stop_job_on_unit PATCH, POST /api/workers//jobs/stop/job_name//experiments/ -update_job_on_unit PATCH /api/workers//jobs/update/job_name//experiments/ -get_workers_and_experiment_assignments GET /api/workers/assignments -remove_all_workers_from_experiments DELETE /api/workers/assignments -stop_all_jobs_in_experiment PATCH, POST /api/workers/jobs/stop/experiments/ -setup_worker_pioreactor POST /api/workers/setup -reboot_units POST /api/workers/system/reboot -shutdown_units POST /api/workers/system/shutdown -static GET /static/ -run_job PATCH, POST /unit_api/jobs/run/job_name/ -get_all_running_jobs GET /unit_api/jobs/running -get_running_jobs_for_experiment GET /unit_api/jobs/running/experiments/ -stop_all_jobs PATCH, POST /unit_api/jobs/stop/all -stop_all_jobs_by_experiment PATCH, POST /unit_api/jobs/stop/experiment/ -stop_job_by_name PATCH, POST /unit_api/jobs/stop/job_name/ -stop_all_jobs_by_source PATCH, POST /unit_api/jobs/stop/job_source/ -update_job PATCH /unit_api/jobs/update/job_name/ -install_plugin PATCH, POST /unit_api/plugins/install -get_installed_plugins GET /unit_api/plugins/installed -get_plugin GET /unit_api/plugins/installed/ -uninstall_plugin PATCH, POST /unit_api/plugins/uninstall -reboot PATCH, POST /unit_api/system/reboot -remove_file PATCH, POST /unit_api/system/remove_file -shutdown PATCH, POST /unit_api/system/shutdown -update_app_and_ui PATCH, POST /unit_api/system/update -update_target PATCH, POST /unit_api/system/update/ -task_status GET /unit_api/task_results/ -get_app_version GET /unit_api/versions/app -get_ui_version GET /unit_api/versions/ui +Endpoint Methods Rule +----------------------------------------------------- ----------- ---------------------------------------------------------------------------------- +api.create_or_update_new_calibrations PUT /api/calibrations +api.get_available_calibrations_type_by_unit GET /api/calibrations/ +api.get_available_calibrations_of_type GET /api/calibrations// +api.get_calibration_by_name GET /api/calibrations/// +api.patch_calibrations PATCH /api/calibrations/// +api.get_current_calibrations_of_type GET /api/calibrations///current +api.get_configs GET /api/configs +api.get_config GET /api/configs/ +api.update_config PATCH /api/configs/ +api.get_historical_config_for GET /api/configs//history +api.get_automation_contrib GET /api/contrib/automations/ +api.get_charts_contrib GET /api/contrib/charts +api.create_experiment_profile POST /api/contrib/experiment_profiles +api.update_experiment_profile PATCH /api/contrib/experiment_profiles +api.get_experiment_profiles GET /api/contrib/experiment_profiles +api.get_experiment_profile GET /api/contrib/experiment_profiles/ +api.delete_experiment_profile DELETE /api/contrib/experiment_profiles/ +api.get_job_contrib GET /api/contrib/jobs +api.get_experiments GET /api/experiments +api.create_experiment POST /api/experiments +api.delete_experiment DELETE /api/experiments/ +api.update_experiment PATCH /api/experiments/ +api.get_experiment GET /api/experiments/ +api.get_logs GET /api/experiments//logs +api.get_media_rates GET /api/experiments//media_rates +api.get_fallback_time_series GET /api/experiments//time_series// +api.get_growth_rates GET /api/experiments//time_series/growth_rates +api.get_od_readings GET /api/experiments//time_series/od_readings +api.get_od_readings_filtered GET /api/experiments//time_series/od_readings_filtered +api.get_temperature_readings GET /api/experiments//time_series/temperature_readings +api.get_unit_labels GET /api/experiments//unit_labels +api.upsert_unit_labels PATCH, PUT /api/experiments//unit_labels +api.get_list_of_workers_for_experiment GET /api/experiments//workers +api.add_worker_to_experiment PUT /api/experiments//workers +api.remove_workers_from_experiment DELETE /api/experiments//workers +api.remove_worker_from_experiment DELETE /api/experiments//workers/ +api.get_experiments_worker_assignments GET /api/experiments/assignment_count +api.get_latest_experiment GET /api/experiments/latest +api.export_datasets POST /api/export_datasets +api.get_historical_media_used GET /api/historical_media +api.get_historical_organisms_used GET /api/historical_organisms +api.is_local_access_point_active GET /api/is_local_access_point_active +api.get_jobs_running_across_cluster GET /api/jobs/running +api.get_jobs_running_across_cluster_in_experiment GET /api/jobs/running/experiments/ +api.get_settings_for_job_across_cluster_in_experiment GET /api/jobs/settings/job_name//experiments/ +api.get_setting_for_job_across_cluster_in_experiment GET /api/jobs/settings/job_name//experiments//setting/ +api.get_setting_for_job_across_cluster GET /api/jobs/settings/job_name//setting/ +api.get_job_settings_for_worker GET /api/jobs/settings/workers//job_name/ +api.get_job_setting_for_worker GET /api/jobs/settings/workers//job_name//setting/ +api.install_plugin_across_cluster PATCH, POST /api/plugins/install +api.get_plugins_across_cluster GET /api/plugins/installed +api.uninstall_plugin_across_cluster PATCH, POST /api/plugins/uninstall +api.update_app_from_release_archive POST /api/system/update_from_archive +api.update_app POST /api/system/update_next_version +api.upload POST /api/system/upload +api.run_job_on_unit_in_experiment PATCH, POST /api/units//jobs/run/job_name//experiments/ +api.get_running_jobs_on_unit GET /api/units//jobs/running +api.stop_job_on_unit PATCH, POST /api/units//jobs/stop/job_name//experiments/ +api.update_job_on_unit PATCH /api/units//jobs/update/job_name//experiments/ +api.reboot_unit POST /api/units//system/reboot +api.shutdown_unit POST /api/units//system/shutdown +api.get_app_versions_across_cluster GET /api/versions/app +api.get_ui_versions_across_cluster GET /api/versions/ui +api.get_list_of_workers GET /api/workers +api.add_worker PUT /api/workers +api.delete_worker DELETE /api/workers/ +api.get_worker GET /api/workers/ +api.blink_worker POST /api/workers//blink +api.get_experiment_assignment_for_worker GET /api/workers//experiment +api.get_logs_for_unit_and_experiment GET /api/workers//experiments//logs +api.change_worker_status PUT /api/workers//is_active +api.run_job_on_unit_in_experiment PATCH, POST /api/workers//jobs/run/job_name//experiments/ +api.get_running_jobs_on_unit GET /api/workers//jobs/running +api.stop_all_jobs_on_worker_for_experiment PATCH, POST /api/workers//jobs/stop/experiments/ +api.stop_job_on_unit PATCH, POST /api/workers//jobs/stop/job_name//experiments/ +api.update_job_on_unit PATCH /api/workers//jobs/update/job_name//experiments/ +api.get_workers_and_experiment_assignments GET /api/workers/assignments +api.remove_all_workers_from_all_experiments DELETE /api/workers/assignments +api.stop_all_jobs_in_experiment PATCH, POST /api/workers/jobs/stop/experiments/ +api.setup_worker_pioreactor POST /api/workers/setup +api.reboot_units POST /api/workers/system/reboot +api.shutdown_units POST /api/workers/system/shutdown +static GET /static/ +unit_api.run_job PATCH, POST /unit_api/jobs/run/job_name/ +unit_api.get_all_running_jobs GET /unit_api/jobs/running +unit_api.get_running_jobs_for_experiment GET /unit_api/jobs/running/experiments/ +unit_api.get_settings_for_a_specific_job GET /unit_api/jobs/settings/job_name/ +unit_api.update_job PATCH /unit_api/jobs/settings/job_name/ +unit_api.get_specific_setting_for_a_job GET /unit_api/jobs/settings/job_name//setting/ +unit_api.stop_all_jobs PATCH, POST /unit_api/jobs/stop/all +unit_api.stop_all_jobs_by_experiment PATCH, POST /unit_api/jobs/stop/experiment/ +unit_api.stop_job_by_name PATCH, POST /unit_api/jobs/stop/job_name/ +unit_api.stop_all_jobs_by_source PATCH, POST /unit_api/jobs/stop/job_source/ +unit_api.install_plugin PATCH, POST /unit_api/plugins/install +unit_api.get_installed_plugins GET /unit_api/plugins/installed +unit_api.get_plugin GET /unit_api/plugins/installed/ +unit_api.uninstall_plugin PATCH, POST /unit_api/plugins/uninstall +unit_api.reboot PATCH, POST /unit_api/system/reboot +unit_api.remove_file PATCH, POST /unit_api/system/remove_file +unit_api.shutdown PATCH, POST /unit_api/system/shutdown +unit_api.update_app_and_ui PATCH, POST /unit_api/system/update +unit_api.update_target PATCH, POST /unit_api/system/update/ +unit_api.task_status GET /unit_api/task_results/ +unit_api.get_app_version GET /unit_api/versions/app +unit_api.get_ui_version GET /unit_api/versions/ui ``` From `python3 -m flask --debug --app main routes -s rule` diff --git a/user-guide/01-getting-started/02-software-set-up.mdx b/user-guide/01-getting-started/02-software-set-up.mdx index 115e6079..c7e597e0 100644 --- a/user-guide/01-getting-started/02-software-set-up.mdx +++ b/user-guide/01-getting-started/02-software-set-up.mdx @@ -30,7 +30,7 @@ Before you get started, you'll need to have the following: We'll start your blank microSD card. -1. Download the [Pioreactor leader and worker image file](https://github.com/pioreactor/custopizer/releases/latest/download/pioreactor_leader_worker.zip). Leave it as a zip (no need to unzip it). +1. Download the [Pioreactor leader and worker image file](https://github.com/pioreactor/custopizer/releases/latest/download/pioreactor_leader_worker.zip). Leave it as a zip file - no need to unzip it. :::info What is an image file? It's a file that contains all the required software preinstalled on it, including an operating system and our custom Pioreactor software. The image will be installed on the microSD card. @@ -93,7 +93,7 @@ What is an image file? It's a file that contains all the required software prein Waited, but didn't see a blue LED blink, or maybe you missed it? Try pressing on the onboard button, near the side labelled "PWM", and pictured above. If this lights up the blue LED, you're good to move on. Still not working? Try power-cycling the Raspberry Pi, or email us at hello@pioreactor.com. ::: -9. After observing the blue LED flashing, navigate to [http://pioreactor.local](http://pioreactor.local) in a web browser to visit the web interface. If you are using local-access-point, looking for a `pioreactor` wifi network and then visit the link. (Not able to load http://pioreactor.local? Read [Troubleshooting](#pioreactorlocal-in-a-web-browser-is-not-showing-up) below). +9. After observing the blue LED flashing, navigate to [http://pioreactor.local](http://pioreactor.local) in a web browser to visit the web interface. If you are using local-access-point, looking for a `pioreactor` wifi network and then visit the link. (Not able to load http://pioreactor.local? Read [Common Questions](#pioreactorlocal-in-a-web-browser-is-not-showing-up) below). 10. The Pioreactor is now ready for use! Follow [this guide](/user-guide/prepare-vial-for-cultures) to set up your first experiment. 10. **If you're using a Pioreactor 20ml v1.0 (sold prior to May 2024) edit your config.ini to** @@ -119,12 +119,10 @@ Workers are additional Pioreactors that you can control from a single UI. Togeth -2. Follow the same instructions above to write the image to an microSD card. All the settings are the same, including *username* and *password*, **but choose a new hostname**. See note below: +2. Follow the same instructions above to write the image to an microSD card. All the settings are the same, including *username* and *password*, **but choose a new hostname**. Choose a hostname that isn't currently being used in your cluster, ex: `worker01`, `worker02`, etc. Re-using old names is fine, so long as that worker isn't present in your cluster. :::tip - Choose a hostname that isn't currently being used in your cluster, ex: `worker01`, `worker02`, etc. Re-using old names is fine, so long as that worker isn't present in your cluster. - - If you plan to have many Pioreactors, use a leading zero in any numbers, like `pio01`, or `worker01`, etc. + If you plan to have many Pioreactors, use a leading zero in numbers, like `pio01`, or `worker01`, etc. ::: Below is a screenshot of example settings, your settings might be slightly different. @@ -132,9 +130,9 @@ Workers are additional Pioreactors that you can control from a single UI. Togeth Screenshot of what your settings may look like -2. If using a local-access-point on your leader Pioreactor, use the wifi ssid `pioreactor` and password `raspberry`. +2. If using a local-access-point on your leader Pioreactor, use the wifi ssid `pioreactor` and password `raspberry`. Otherwise, use the same wifi credentials are your leader Pioreactor. 3. After the image is written to the microSD card, place the microSD card into the Raspberry Pi and power it on. -4. The Pioreactor's blue LED will light up and stay on, indicating that it's ready to be connected. Move onto the next step. +4. After a few minutes, the Pioreactor's blue LED will light up and stay on, indicating that it's ready to be connected. Move onto the next step. #### Step 2. Add worker to cluster using the UI @@ -149,7 +147,7 @@ On the leader's command line, the command `pio add-pioreactor ` will c We recommend running a [self-test](/user-guide/running-self-test) on all Pioreactors after your initial setup to detect any hardware bugs at this point. ::: -## Troubleshooting +## Common questions #### My leader Pioreactor never flashes the blue LED - First, confirm that when you press the HAT button, the blue LED does not show up. If it does, you're good to go. @@ -171,7 +169,6 @@ On a successful start, the Pioreactor will flash its blue LED for about 2 second * You may have mis-typed your WiFi credentials. To fix this, you'll need to restart the image installation from the Raspberry Pi Imager. * If connecting to a 5GHz WiFi connection, you _need_ to supply a valid country code. See the list here: [https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2/](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 "Link to country codes on wikipedia"). * It's possible your SD card is damaged. This can cause all sorts of problems (including failing to boot), not just WiFi issues. The most common cause of SD card failure is probably inserting or removing the SD card while the Pi is powered up. -* Check out some other possibilities [here](https://community.octoprint.org/t/wifi-setup-and-troubleshooting/184#heading--troubleshooting). #### I want to change the Pioreactor name on installation of leader diff --git a/user-guide/03-Extending your Pioreactor/05-configuration.md b/user-guide/03-Extending your Pioreactor/05-configuration.md index bf359b0b..da7ef402 100644 --- a/user-guide/03-Extending your Pioreactor/05-configuration.md +++ b/user-guide/03-Extending your Pioreactor/05-configuration.md @@ -35,19 +35,15 @@ Pioreactor also stores a history of changes to each configuration file. You can ![Select historical versions of config.ini's](/img/user-guide/choose_config_version2.png) - ### Editing the configuration files from the command line -All the `.ini` files come from the leader unit. They are stored in `/home/pioreactor/.pioreactor` - one `config.ini` and a `config_.ini` for each Pioreactor unit. The command `pios sync-configs` will deploy the `.ini` files to their correct unit. Editing the `.ini` files on the leader is correct workflow, as any edits on the worker units will be overwritten on the next `pios sync-configs`. - -One can programmatically, or by hand, edit the `config_.ini` files to create varying parameters in an experiment. Running `pios sync-configs` will deploy the config files. - +All the `.ini` files come from the leader unit. They are stored in `/home/pioreactor/.pioreactor` - the `config.ini` and a `config_.ini` for each Pioreactor unit. The command `pios sync-configs` will deploy the `.ini` files to their correct unit. Editing the `.ini` files on the leader is correct workflow, as any edits on the worker units will be overwritten on the next `pios sync-configs`. ### Editing the `config.ini` before booting Sometimes it's desirable to make changes to the `config.ini` without having to boot the Pioreactor first. You can do this by plugging the microSD card into your computer, and adding a `config.ini` to the `boot/` folder on it. This `config.ini` doesn't need to have all the fields, only the fields you wish to change. At start up, the Pioreactor will merge `/boot/config.ini` into the Pioreactor's `config.ini`, and then delete `/boot/config.ini`. -### Example `config.ini` +### Default `config.ini` -If you need a reference config.ini, or to replace parts of yours, here's our [default one](https://raw.githubusercontent.com/Pioreactor/CustoPiZer/pioreactor/workspace/scripts/files/config.example.ini) that ships with the Raspberry Pi image. To use it, you'll need to make some changes, specifically to \`cluster.leader\` and \`inventory\`. +If you need a reference config.ini, or to replace parts of yours, here's our [default one](https://raw.githubusercontent.com/Pioreactor/CustoPiZer/pioreactor/workspace/scripts/files/config.example.ini) that ships with the Raspberry Pi image. To use it, you'll need to make some changes to populate the leader, specifically to \`cluster.topology\` and \`mqtt\`. diff --git a/user-guide/30-Advanced/01-cli.md b/user-guide/30-Advanced/01-cli.md index 3d595e4d..2b10e6b6 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 --name --experiment ` or `pio kill --all-jobs` to end jobs. +* `pio kill --job-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 version. @@ -41,7 +41,7 @@ The leader also has their own unique set of `pio` commands (these commands do no The leader Pioreactor 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 Pioreactor are the following: -* `pios kill --name ` terminate the job `` on the workers. Ex: `pios kill --name dosing_automation`. +* `pios kill --job-name ` terminate the job `` on the workers. Ex: `pios kill --job-name dosing_automation`. * `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`. * `pios update` install the latest Pioreactor software on each worker. * `pios sync-configs` deploy the config.ini files to workers. @@ -49,7 +49,7 @@ The leader Pioreactor interacts with the worker computers using the `pios` comma * `pios plugins uninstall ` will uninstall the plugin on each worker _and_ the leader. * `pios reboot` will reboot all workers, by default, in the cluster. See `--units` arg below. * `pios shutdown` will shut down all workers, by default, in the cluster. See `--units` arg below. -* `pios cp ` will copy (and overwrite) `filepath` on the leader to all the workers. +* `pios cp ` will copy (and possibly overwrite) `filepath` on the leader to all the workers. * `pios rm ` will remove `filepath` on all the workers. :::tip