Metadata-Version: 2.1
Name: picamera-mqtt
Version: 0.0.5
Summary: MQTT-based control and image capture with local and remote networked Raspberry Pi cameras.
Home-page: https://github.com/ethanjli/picamera-mqtt
Author: Ethan Li
Author-email: lietk12@gmail.com
License: BSD 3-Clause License
Description: # picamera-mqtt
        MQTT-based control and image capture with local and remote networked Raspberry Pi cameras.
        Deployment scripts needs to be run from a Raspberry Pi. Other scripts can be run from any computer.
        
        ## MQTT Broker Server Setup
        
        To run the MQTT broker server, edit `deploy/config/broker.conf` and then run
        `deploy/mqtt_broker.sh`.
        
        ### Broker Autostart
        To automatically run the MQTT broker when the host Raspberry Pi starts up,
        install the `mqtt_broker.service` systemd unit:
        ```
        cd ~/Desktop/picamera-mqtt
        sudo cp deploy/systemd/mqtt_broker.service /etc/systemd/system/mqtt_broker.service
        sudo systemctl enable mqtt_broker
        ```
        You can manually start the service with systemd, view the status of the service with systemd,
        view its output logs with journalctl, or kill the script with systemd:
        ```
        sudo systemctl start mqtt_broker
        systemctl status mqtt_broker
        journalctl -u mqtt_broker
        sudo systemctl stop mqtt_broker
        ```
        
        ## Camera Client Deployment Setup
        
        These instructions are for setting up a Raspberry Pi to deploy a camera imaging client.
        
        ### Preparation
        You will need to install some packages on the Raspberry Pi, as follows:
        ```
        sudo apt-get update
        sudo apt-get upgrade
        sudo apt-get install git python3-pip
        sudo apt-get install vim byobu wicd-curses # optional, but makes your life easier
        ```
        
        You will need to use the `raspi-config` tool to change the password of the pi user,
        set the locale to `en_US UTF-8`, set the keyboard layout to `English (US)`,
        change the hostname of the Raspberry Pi, and set the Raspberry Pi to wait for an
        internet connection upon startup.
        
        You will need to edit the `/etc/wpa_supplicant/wpa_supplicant.conf` configuration
        file to connect to wi-fi if you are deploying the Raspberry Pi with a Wi-Fi connection.
        
        ### Client Hardware Setup
        Connect a Raspberry Pi Camera to the Raspberry Pi.
        
        ### Client Software Setup
        Clone this repo, for example with:
        ```
        cd ~/Desktop
        git clone https://github.com/ethanjli/picamera-mqtt.git
        ```
        Install required dependencies from `requirements_deployment.txt`, for example with:
        ```
        cd ~/Desktop/picamera-mqtt
        sudo pip3 install -r requirements_deployment.txt
        ```
        Then confirm that the camera works correctly by running the `capture.py` script,
        as follows:
        ```
        cd ~/Desktop/picamera-mqtt
        python3 -m picamera_mqtt.tests.imaging.capture
        ```
        This should cause the appearance of two files, `capture_pil.jpg` and
        `capture_final.jpg`, in your working directory.
        
        ### Client Config
        You will need to edit the `deploy/config/settings.json` config file such that:
        
        - The `hostname` parameter is either `localhost` (if your MQTT broker is running
          on the same computer as your client) or the IP address of the computer running
          your MQTT broker.
        - The `client_name` parameter and the `target_name` parameter both should say
          `camera_n`, where `n` should be replaced with a unique id number of your camera
          client. This id number will be used to uniquely label each camera stream.
        
        
        ### Camera Client Software Autostart
        To automatically run the camera MQTT client when the Raspberry Pi starts up,
        install the `mqtt_imaging.service` systemd unit:
        ```
        cd ~/Desktop/picamera-mqtt
        sudo cp deploy/systemd/mqtt_imaging.service /etc/systemd/system/mqtt_imaging.service
        sudo systemctl enable mqtt_imaging
        ```
        You can manually start the service with systemd, view the status of the service with systemd,
        view its output logs with journalctl, or kill the script with systemd:
        ```
        sudo systemctl start mqtt_imaging
        systemctl status mqtt_imaging
        journalctl -u mqtt_imaging
        sudo systemctl stop mqtt_imaging
        ```
        
        ## Ad Hoc Wi-Fi Network Setup
        
        To acquire images from multiple Raspberry Pi cameras, each camera should be
        connected to a Raspberry Pi board. A Raspberry Pi 3 B+ should be running the
        `mqtt_broker` service, and it can also run the `mqtt_imaging` service for the
        camera attached to it. The other Raspberry Pi boards (e.g. Raspberry Pi Zero W)
        should be running the `mqtt_imaging` service for their respective cameras. Then
        the Raspberry Pi 3 needs to be configured to host a simple ad hoc wi-fi network.
        
        ### Enabling the Ad Hoc Network
        NOTE: This currently doesn't work correctly. Instead of setting up an ad hoc
        network, the Raspberry Pi boards all need to be connected to some wireless
        access point.
        
        The details of enabling and disabling the ad hoc network are managed by the
        [simondlevy/RPiAdHocWiFi repo](https://github.com/simondlevy/RPiAdHocWiFi):
        ```
        cd ~/Desktop
        git clone https://github.com/simondlevy/RPiAdHocWiFi.git
        ```
        
        To enable the ad hoc network, run the following and reboot the Raspberry Pi:
        ```
        cd ~/Desktop/RPiAdHocWiFi
        sudo ./install.sh
        ```
        This will create an ad hoc network with SSID `Raspberry-Pi-1`, and the Raspberry Pi
        will be accessible at IP address `192.168.2.2`.
        
        ### Connecting to the Ad Hoc Network
        To configure the other Raspberry Pi boards, copy `deploy/adhoc/rc.local` to
        `/etc/rc.local`:
        ```
        cd ~/Desktop/picamera-mqtt
        sudo cp deploy/adhoc/rc.local /etc/rc.local
        ```
        and copy `deploy/adhoc/wpa_supplicant.conf` to `/etc/wpa_supplicant/wpa_supplicant.conf`:
        ```
        cd ~/Desktop/picamera-mqtt
        sudo cp deploy/adhoc/wpa_supplicant.conf /etc/wpa_supplicant/wpa_supplicant.conf
        ```
        
        ## System Tests
        
        With an operational camera client connected to the MQTT broker server, you can run
        a few tests on the computer running the MQTT broker server to confirm correct image
        transfer:
        ```
        cd ~/Desktop/picamera-mqtt
        python3 -m picamera_mqtt.tests.mqtt_clients.mock_host --interval 8 --config settings_localhost.json
        ```
        
        This will exercise roundtrip communication to and from the camera client with
        client name `camera_1` by sending image acquisition messages to the camera client
        every 8 seconds and receiving (and discarding) images captured by the camera client.
        
        To save these images, run the following test:
        ```
        cd ~/Desktop/picamera-mqtt
        python3 -m picamera_mqtt.tools.timelapse_host --interval 15 --number 5
        ```
        This will take a timelapse of 5 images spaced out at 15-second intervals from
        all camera clients connected to the broker with client names `camera_1`, `camera_2`,
        and `camera_3`; the client names queried can be changed by editing the config file.
        By default, images will be saved to the `data` directory, but you can change this
        with the `--output_dir` flag to specify a different path.
        
        If you only want to capture image snapshots at a single time point, run the following test:
        ```
        cd ~/Desktop/picamera-mqtt
        python3 -m picamera_mqtt.tools.acquire_host
        ```
        By default, images will be saved to the `data` directory, but you can change this
        with the `--output_dir` flag to specify a different path. By default, images will
        be saved with filenames with `acquire` at the start, but you can change this with
        the `--output_prefix` flag to specify a different filename prefix.
        
        ## System Administration
        
        You can remotely send deployment management commands to the Raspberry Pi client
        by sending messages over the `deployment` topic. The
        `picamera_mqtt/tools/deploy/mqtt_send_deployment` script lets you do this
        from the command-line, as follows:
        ```
        cd ~/hand-hygiene/intervention
        python3 -m intervention_system.tools.mqtt_send_deployment shutdown --target_name camera_1 # shut down the Raspberry Pi running camera 1
        python3 -m intervention_system.tools.mqtt_send_deployment reboot --target_name camera_1 # reboot the Raspberry Pi running camera 1
        python3 -m intervention_system.tools.mqtt_send_deployment stop --target_name camera_1 # stop the illumination client running camera 1
        python3 -m intervention_system.tools.mqtt_send_deployment restart --target_name camera_1 # restart the illumination client running camera 1
        python3 -m intervention_system.tools.mqtt_send_deployment "git pull" --target_name camera_1 # update the repo and restart the illumination client running camera 1
        ```
        
        ## Camera Parameter Adjustment
        
        You can remotely send camera parameter update commands to the Raspberry Pi client
        by sending messages over the `control` topic. The
        `picamera_mqtt/tools/deploy/mqtt_send_camera_params` script lets you do this
        from the command-line, as follows:
        ```
        cd ~/hand-hygiene/intervention
        python3 -m intervention_system.tools.mqtt_send_camera_params --target_name camera_1 # query camera parameters from camera 1
        python3 -m intervention_system.tools.mqtt_send_camera_params --target_name camera_1 --roi_zoom 1.5 # set camera zoom factor to 1.5 on camera 1
        python3 -m intervention_system.tools.mqtt_send_camera_params --target_name camera_1 --shutter_speed 200 # set shutter speed to 200 ms on camera 1
        python3 -m intervention_system.tools.mqtt_send_camera_params --target_name camera_1 --iso 200 # set ISO to 200 on camera 1
        python3 -m intervention_system.tools.mqtt_send_camera_params --target_name camera_1 --resolution_width 1920 --resolution_height 1080 # set the image resolution to 1920x1080 on camera 1
        python3 -m intervention_system.tools.mqtt_send_camera_params --target_name camera_1 --awb_gain_red 2.0 # set AWB red gain to 2.0 on camera 1
        python3 -m intervention_system.tools.mqtt_send_camera_params --target_name camera_1 --awb_gain_blue 2.0 # set AWB blue gain to 2.0 on camera 1
        ```
        Note that all camera param flags can be combined into a single command if you wish.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Topic :: Multimedia :: Graphics :: Capture :: Digital Camera
Description-Content-Type: text/markdown
Provides-Extra: picamera_client
Provides-Extra: mock_camera_client
