planktoscope/docs/update_device-tree.md

127 lines
6.5 KiB
Markdown
Raw Normal View History

2021-01-21 13:23:44 +01:00
# Using a flash with the camera
The Pi's camera module includes an LED flash driver which can be used to illuminate a scene upon capture. The flash driver has two configurable GPIO pins:
2022-11-03 14:16:53 +01:00
- one for connection to an LED based flash (xenon flashes won't work with the camera module due to it having a `rolling shutter`). This will fire before (`flash metering`) and during capture
- one for an optional privacy indicator (a requirement for cameras in some jurisdictions). This will fire after taking a picture to indicate that the
2021-01-21 13:23:44 +01:00
camera has been used
These pins are configured by updating the `VideoCore device tree blob`. Firstly, install the device tree compiler, then grab a copy of the default
device tree source:
2022-11-03 14:16:53 +01:00
```sh
sudo apt-get install device-tree-compiler
wget https://github.com/raspberrypi/firmware/raw/master/extra/dt-blob.dts
2021-01-21 13:23:44 +01:00
```
The device tree source contains a number of sections enclosed in curly braces, which form a hierarchy of definitions. The section to edit will depend on which revision of Raspberry Pi you have (check the silk-screen writing on the board for the revision number if you are unsure):
2022-11-03 14:16:53 +01:00
| Model | Section |
| -------------------------------------- | :----------------------- |
| Raspberry Pi Model B rev 1 | `/videocore/pins_rev1` |
| Raspberry Pi Model A and Model B rev 2 | `/videocore/pins_rev2` |
| Raspberry Pi Model A+ | `/videocore/pins_aplus` |
| Raspberry Pi Model B+ rev 1.1 | `/videocore/pins_bplus1` |
| Raspberry Pi Model B+ rev 1.2 | `/videocore/pins_bplus2` |
| Raspberry Pi 2 Model B rev 1.0 | `/videocore/pins_2b1` |
| Raspberry Pi 2 Model B rev 1.1-1.2 | `/videocore/pins_2b2` |
| Raspberry Pi 3 Model B rev 1.0 | `/videocore/pins_3b1` |
| Raspberry Pi 3 Model B rev 1.2 | `/videocore/pins_3b2` |
| Raspberry Pi Zero rev 1.2-1.3 | `/videocore/pins_pi0` |
2021-01-21 13:23:44 +01:00
Under the section for your particular model of Pi you will find `pin_config` and `pin_defines` sections. Under the `pin_config` section you need to configure the GPIO pins you want to use for the flash and privacy indicator as using pull down termination. Then, under the `pin_defines` section you need to associate those pins with the `FLASH_0_ENABLE` and `FLASH_0_INDICATOR` pins.
For example, to configure GPIO 17 as the flash pin, leaving the privacy indicator pin absent, on a Raspberry Pi 2 Model B rev 1.1 you would add the following line under the `/videocore/pins_2b2/pin_config` section:
2022-11-03 14:16:53 +01:00
```txt
pin@p17 { function = "output"; termination = "pull_down"; };
2021-01-21 13:23:44 +01:00
```
2022-11-03 14:16:53 +01:00
Please note that GPIO pins will be numbered according to the `Broadcom pin numbers`(BCM mode in the RPi.GPIO library, _not_ BOARD mode). Then change the following section under `/videocore/pins_2b2/pin_defines`. Specifically, change the type from "absent" to "internal", and add a number property defining the flash pin as GPIO 17:
2021-01-21 13:23:44 +01:00
2022-11-03 14:16:53 +01:00
```c
pin_define@FLASH_0_ENABLE {
type = "internal";
number = <17>;
};
2021-01-21 13:23:44 +01:00
```
With the device tree source updated, you now need to compile it into a binary blob for the firmware to read. This is done with the following command line:
2022-11-03 14:16:53 +01:00
```sh
dtc -q -I dts -O dtb dt-blob.dts -o dt-blob.bin
2021-01-21 13:23:44 +01:00
```
Dissecting this command line, the following components are present:
2022-11-03 14:16:53 +01:00
- `dtc` - Execute the device tree compiler
- `-I dts` - The input file is in device tree source format
- `-O dtb` - The output file should be produced in device tree binary format
- `dt-blob.dts` - The first anonymous parameter is the input filename
- `-o dt-blob.bin` - The output filename
This should output nothing. If you get lots of warnings, you've forgotten the `-q` switch; you can ignore the warnings. If anything else is output, it will most likely be an error message indicating you have made a mistake in the device tree source. In this case, review your edits carefully (note that sections and properties _must_ be semi-colon terminated for example), and try again.
2021-01-21 13:23:44 +01:00
Now the device tree binary blob has been produced, it needs to be placed on the first partition of the SD card. In the case of non-NOOBS Raspbian installs, this is generally the partition mounted as `/boot`:
2022-11-03 14:16:53 +01:00
```sh
sudo cp dt-blob.bin /boot/
2021-01-21 13:23:44 +01:00
```
However, in the case of NOOBS Raspbian installs, this is the recovery partition, which is not mounted by default:
2022-11-03 14:16:53 +01:00
```sh
sudo mkdir /mnt/recovery
sudo mount /dev/mmcblk0p1 /mnt/recovery
sudo cp dt-blob.bin /mnt/recovery
sudo umount /mnt/recovery
sudo rmdir /mnt/recovery
2021-01-21 13:23:44 +01:00
```
Please note that the filename and location are important. The binary blob must be named `dt-blob.bin` (all lowercase), and it must be placed in the root
directory of the first partition on the SD card. Once you have rebooted the Pi (to activate the new device tree configuration) you can test the flash with the following simple script:
2022-11-03 14:16:53 +01:00
2021-01-21 13:23:44 +01:00
```python
2022-11-03 14:16:53 +01:00
import picamera
2021-01-21 13:23:44 +01:00
2022-11-03 14:16:53 +01:00
with picamera.PiCamera() as camera:
camera.flash_mode = 'on'
camera.capture('foo.jpg')
2021-01-21 13:23:44 +01:00
```
You should see your flash LED blink twice during the execution of the script.
!!! warning
2022-11-03 14:16:53 +01:00
The GPIOs only have a limited current drive which is insufficient for powering the sort of LEDs typically used as flashes in mobile phones. You will require a suitable drive circuit to power such devices, or risk damaging your Pi.
2021-01-21 13:23:44 +01:00
2022-11-03 14:16:53 +01:00
For reference, the flash driver chips we have used on mobile phones will often drive up to 500mA into the LED. If you're aiming for that, then please think about your power supply too.
2021-01-21 13:23:44 +01:00
2022-11-03 14:16:53 +01:00
If you wish to experiment with the flash driver without attaching anything to the GPIO pins, you can also reconfigure the camera's own LED to act as the flash LED. Obviously this is no good for actual flash photography but it can demonstrate whether your configuration is good. In this case you need not add anything to the `pin_config` section (the camera's LED pin is already defined to use pull down termination), but you do need to set `CAMERA_0_LED` to absent, and `FLASH_0_ENABLE` to the old `CAMERA_0_LED` definition (this will be pin 5 in the case of `pins_rev1` and `pins_rev2``, and pin 32 in the case of everything else).
For example, change:
```c
pin_define@CAMERA_0_LED {
type = "internal";
number = <5>;
};
pin_define@FLASH_0_ENABLE {
type = "absent";
};
2021-01-21 13:23:44 +01:00
```
into this:
2022-11-03 14:16:53 +01:00
```c
pin_define@CAMERA_0_LED {
type = "absent";
};
pin_define@FLASH_0_ENABLE {
type = "internal";
number = <5>;
};
2021-01-21 13:23:44 +01:00
```
After compiling and installing the device tree blob according to the instructions above, and rebooting the Pi, you should find the camera LED now
2022-11-03 14:16:53 +01:00
acts as a flash LED with the Python script above.