Updated docs to refer back to website

Microscope configuration is made persistent via a microscope runtime-config (RC) file. By default, this

file exists at ``~/.openflexure/microscope_settings.yaml``, and contains basic parameters to set up the microscope.

Additionally, by default, configurations for specific pieces of hardware (i.e. the Pi camera) are located

Additionally, by default, configurations for specific pieces of hardware (i.e. the stage and camera) are located

in separate "auxillary" config files, and are linked together by adding the config file's path to your main

microscope RC file. This is set up by default, as shown below:

Default microscope_settings.yaml

++++++++++++++++++++++++++++++++

.. code-block:: yaml

    # Resolutions for streaming and capture

    stream_resolution: [832, 624]

    image_resolution: [2592, 1944]

    numpy_resolution: [1312, 976]

    # Field of view, in stage steps

    fov: [4100, 3146]

    # Capture quality

    jpeg_quality: 75

    # Parameters specific to PiCamera objects

    picamera_settings: ~/.openflexure/picamera_settings.yaml

    # Default plugins

    plugins:

    - openflexure_microscope.plugins.default.autofocus:AutofocusPlugin

    - openflexure_microscope.plugins.default.camera_calibration:Plugin

Example picamera_settings.yaml

++++++++++++++++++++++++++++++

.. code-block:: yaml

    analog_gain: !!python/object/apply:fractions.Fraction ['1']

    awb_gains: !!python/tuple

    - !!python/object/apply:fractions.Fraction [221/256]

    - !!python/object/apply:fractions.Fraction [709/256]

    awb_mode: auto

    digital_gain: !!python/object/apply:fractions.Fraction [585/256]

    exposure_mode: auto

    framerate: !!python/object/apply:picamera.mmalobj.PiCameraFraction ['30']

    lens_shading_table: ...

    saturation: 0

    shutter_speed: 0

microscope RC file. 

Loading the runtime-config

Install

-------

Quick-installer

Stable installation

+++++++++++++++

For most users, this is the reccommended installation method.

    - See the `GitLab repo <https://gitlab.com/openflexure/openflexure-microscope-installer>`_ for details.

- Follow on-screen prompts

Really-quick installer

^^^^^^^^^^^^^^^^^^^^^^

The installer script can run with all default settings applied, removing all user prompts.

- Run ``curl -LSs get.openflexure.org/microscope |sudo bash -s -- -y``

Developer installer

Developer installation

^^^^^^^^^^^^^^^^^^^

The installer script can pull the latest development package from our git repository, and use install into a developer environment using Poetry.

Manual installation

+++++++++++++++++++

- (Recommended) create a virtual environment

    - ``pip3 install virtualenv``

    - ``mkdir ~/.openflexure``

    - ``python3 -m virtualenv ~/.openflexure/envmicroscope``

    - Activate with ``source /.openflexure/envmicroscope/bin/activate``

- (Recommended) create and activate a virtual environment

- Install non-python dependencies with ``sudo apt-get install libatlas-base-dev libjasper-dev libjpeg-dev``

- **Users:** Install module by running ``pip install openflexure-microscope``

- **Developers:** Install `Poetry <https://github.com/sdispater/poetry>`_, clone this repo, and ``poetry install`` from inside the repo.

API Server

----------

If you use the auto-installer, a system.d service will be generated automatically, and you will be prompted to enable it at startup.

The service can be controlled with the following commands:

===================  ====

**Start**            ``sudo systemctl start ofmserver``

**Stop**             ``sudo systemctl stop ofmserver``

**Restart**          ``sudo systemctl restart ofmserver``

**Check status**     ``sudo systemctl status ofmserver``

**Disable on-boot**  ``sudo systemctl disable ofmserver``

**Enable on-boot**   ``sudo systemctl enable ofmserver``

===================  ====

- Install `Poetry <https://github.com/sdispater/poetry>`_, clone this repo, and ``poetry install`` from inside the repo.

Manually starting the server with Gunicorn

++++++++++++++++++++++++++++++++++++++++++

Managing the server

-------------------

This can be especially useful for developers, giving more immediate feedback on the status of the server.

Managing the server through the installer script's CLI is documented `on our website <https://openflexure.gitlab.io/projects/microscope/#managing-the-microscope-server>`_.

- Ensure Gunicorn is installed to the current environment (``pip install gunicorn``)

- Run ``gunicorn --threads 5 --workers 1 --graceful-timeout 3 --bind 0.0.0.0:5000 openflexure_microscope.api.app:app``

    - We spawn 5 threads to handle simultaneous connections

    - We spawn a single worker as only one process can access the Pi camera simultaneously

    - We shorten the graceful-timeout to 3 seconds, to avoid stalling if a camera feed connection is active

    - Binding to 0.0.0.0:5000 opens the server up on port 5000 to devices outside of localhost

 No newline at end of file

This includes starting the server as a background service, as well as starting a development server with real-time debug logging.

 No newline at end of file