Merge pull request #16 from schoolpost/update

Update
This commit is contained in:
Csaba Nagy 2023-04-18 22:13:58 -06:00 committed by GitHub
commit a3fcde19df
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 47425 additions and 17639 deletions

9
.gitmodules vendored Normal file
View File

@ -0,0 +1,9 @@
[submodule "software/cinepi-raw"]
path = software/cinepi-raw
url = https://github.com/cinepi/cinepi-raw.git
[submodule "software/udev-media-automount"]
path = software/udev-media-automount
url = https://github.com/cinepi/udev-media-automount.git
[submodule "software/libcamera"]
path = software/libcamera
url = https://github.com/cinepi/libcamera.git

View File

@ -1,77 +1,35 @@
# CinePI
![](https://img.shields.io/badge/CinePi2K-1.0.0-red.svg)
Software to enable Cinema Camera capabilities for Raspberry Pi
# CinePI V2: OpenSource Cinema Camera using Raspberry Pi
![Banner](docs/images/hero-banner.jpg)
 
![Banner](docs/banner.jpg)
# Introduction
 
# Software Overview
The CinePI V2 is an OpenSource Camera design utilzing off-the-shelf / DIY hardware & software from vendors including: Raspberry Pi, Pimoroni, Adafruit, Sparkfun, etc...
Description of the software side of the camera which involve multiple layers of logic/configuration at the application ( userspace ) and kernel level.
The purpose of this repository and it's accomanying resocures is primarly to act as a template / starting point for your own design. CAD files are included for you to modify the enclosure to your needs, feel free to experiment with the parts used; use a different set of buttons, RTC, display, etc... the only components that cannot be changed are the Raspberry Pi 4B and the High Quality Camera Module.
 
> ## Notice
>
> This design makes a number of modifications to hardware, as such is not recommended for those not comfortable with a soldering iron.
>
> Warranties may be void. I am not responsible for any damages that accompany hardware modifications.
***
## **Architecture**:
This section will highlight the logic responsible for dealing with the RAW frames streamed from the image sensor.
# Features
```
V4L2 ( Unicam ) -> V4L2Copy -> V4L2 Loopback Device -> yavtad/rawcam -> live_view_display
-> yavtar2/rawcam -> save_dng_frames
```
- 4.0" High Res Touch Screen Interface
- Internal High Capacity Battery
- Real time clock
- USB 3.0 External SSD Recording
- 1/4" Mounting Points
- 40mm Noctua Cooling System
### **V4L2 Loopback**
V4L2 Loopback is used to create a virtual V4L2 device that will act as the source for our RAW frames.
V4L2 Loopback allows for multiple applications to access the same device at the same time and in this way acts a "poor-mans multi-threaded" experience where we can have say one application access the RAW frames for live view and a seperate application access the same RAW frames for saving to disk. This way one will not necessearily affect the other and they stay independant* ( conceptually this is what I expected but in practice this is not necessarily true and comes with quirks. **This is not the way to implement actual multi-threading so simply acts a temporary solution for the time being.** )
# Guide
 
Refer to the Wiki section for in-depth guide on hardware assembly and software installation.
### **V4L2Copy ( V4L2Utils)**
V4L2Utils comes bundled with a very handy utility V4L2Copy that as it's name might suggest, can copy the data from one V4L2 device to another. This is used to copy data from the original camera V4L2 source ( /dev/video0 ) to our new virtual V4L2 device ( /dev/video4 ).
# References
 
CinePI Project Account | [Github Page](https://github.com/cinepi)
### **Yavta ( 6by9 fork )**
This specific application is where the actual processing of RAW frames happens. This forked version was tuned to work the Raspberry Pi High Quality Camera and in this particualr project is used in two parts:
1. **yavtad/rawcam | Live view Display:** This application is modified to specifically handle the rendering of RAW frames to the display ( HDMI ) and has all the necessary MMAL settings to create a proper live view. ( Gamma, CCM, etc.. )
2. **yavtar2/rawcam | RAW Frame Recorder:** This application is modified specifically to handle the saving of RAW frames to disk. Also handles the GPIO logic for start/stop trigger and live timecode display.
 
### Summary: V4L2Copy is used to pipe RAW frames from the original V4L2 device to our new virtual V4L2 Loopback device. Two seperate instances of Yavta are used to read RAW frames from our virtual device to perform liveview and recording capabilities.
 
 
***
## **Main process**:
The section will highlight the main process that is spawned at bootup. It is responsible for further spawning and managing of 3 sub-processes that comprise of the entire camera system.
```
camera/cameracore3.py -> camera/cameracore2.py ( configures VL42 and starts both yavta instances)
-> controls-thread/bmdproxy.py ( bluetooth service )
-> mmal_render_ui/render ( live_view overlays )
```
### **cameracore3**
This python script is responsible for spawning the 3 main sub-processes necessary for the entire camera system. This script is called at bootup via rc.local
### **cameracore2**
This python script is responsible for spawning and managing the both the live-view and frame recording yavta instances based on current frame dimensions.
### **bmdproxy**
This python script initializes the BLE server that implements logic that allows it to interface with applications that use the Blackmagic Camera Control Protocol over bluetooth.
### **mmal_ui_render**
This application implements the logic to read/update/draw the necessary live view settings overtop of the live view image.
 
![Banner](docs/banner2.jpg)
# Hardware Overview
Coming soon...

View File

@ -1,188 +0,0 @@
# User Guide
**Early Disclaimer: CinePI-2K's [current release](https://github.com/schoolpost/CinePI/releases) is far from being considered stable, so use it at your own risk. Do not expect it to work flawlessly. Expect lots of bugs and dropped frames! This is just the nature of things, but hopefully through a collaborative effort, we'll get to a stable working version soon!**
## Installation
You find the current CinePI-2K release [here](https://github.com/schoolpost/CinePI/releases). The software is currently being distributed as a standalone operating system installation image for the Raspberry Pi (based on a modified [Raspberry Pi OS](https://www.raspberrypi.org/software/operating-systems/)). The source code will be made available in CinePI-2K's main GitHub repository.
It is difficult to package CinePI as an installable "app" for existing Raspberry Pi operating system installations due to its particular dependencies on specific operating system/Linux kernel-level configurations. Releases and packaging will be assessed and revisited in the future.
### Installation Requirements:
- Raspberry Pi 4 Model B with 4GB or more. Models with less RAM are untested. Currently, more RAM allows longer video takes, so the 8GB model is preferable.
- Preferably an additional heat sink with cooling fans for the Raspberry Pi. These are being offered by various third-party manufacturers. It must leave access to the GPIO and camera ports.
- Raspberry Pi High Quality Camera module
- 8GB Micro SD card for the CinePI-2K operating system. (You can also use larger cards if 8GB are not available, but they won't offer any advantage.)
- Twin Dupont cable and a momentary push button. (These can be bought for a few dollars in any electronics supply store. When the CinePi isn't built into a protective camera housing, a push button with screw connectors for the cables will be more robust than a push button that requires soldering the cables to it.) You can also skip the push button and simply leave the two blank cable ends available to the camera operator, who would then have to briefly short-circuit them in order to trigger recording.
- A fast external USB 3.x SSD drive to act as your camera's storage medium. Samsung's T5 drives are a proven solution. Other USB SSD drives (respectively USB housings for SATA or NVME SSDs) can be used if they support USB 3 and the UASP protocol. Make sure to connect the drive to one the Raspberry Pi's USB 3 ports (the ones with the blue socket) using the USB cable included with the drive, or a USB 3 cable that reliably supports high transfer speeds. Slow media or wrong cables will result in dropped frames.
The USB SSD disk can be formatted in **ExFAT** (universal file system for flash memory) / **EXT4** (Linux file system) / **NTFS** (Windows file system). EXT4 is recommended and performs currently the best, next best is ExFAT. NTFS is supported but not recommended due to ongoing development of the NTFS3 driver that is used in this release.
**Disks must be labeled "RAW" when being formatted. The CinePI-2K will not recognize disks without this label.**
- HDMI display/monitor, with a suitable cable to connect it to the Raspberry Pi's Micro HDMI port. A video field monitor (with focus peaking, zebras and punch-in focus) is highly recommended; budget models ($100-$200) are sufficient.
- For using the camera in the field, a USB power bank with power delivery (PD), or a comparable solution for mobile USB power (such as [Blind Spot Gear's Power Junkie](https://www.blindspotgear.com/power-junkie) for Sony NP-F batteries if you want to use the same batteries for the camera and a video field monitor).
- For controlling the camera's settings (ISO, shutter angle, white balance), you need a smartphone app that talks to the CinePI-2K via Bluetooth using Blackmagic's Bluetooth camera control protocol originally developed for the Blackmagic Pocket 4K and 6K cameras. Existing iOS and Android apps for those cameras should be principally be able to control the CinePI-2K. The following iOS app has been tested and does work:
- [Bluetooth+ for Blackmagic](https://apps.apple.com/us/app/bluetooth-for-blackmagic/id1376947780)
The following Android app works principally:
- [My Camera Controller](https://play.google.com/store/apps/details?id=com.taskdesigns786.android.mycameracontroller)
***
### Flashing
Download the zipped CinePI-2K image from the [release page](https://github.com/schoolpost/CinePI/releases) and unzip it.
You will need a disk flashing utility, such as these listed below:
- [Etcher](https://www.balena.io/etcher/) (Windows, MacOS, Linux)
- [Win32DiskImager](https://sourceforge.net/projects/win32diskimager/) (Windows)
Put your Micro SD card into an SD card reader connected to you computer (if necessary, using a full-size SD card adapter). Start the disk flashing utility, select the CinePI-2K image and flash it to the Micro SD card.
***
### Configuration ( MUST READ )
CinePI-2K in its current form **heavily benefits from overclocking** above the base speed of the Raspberry Pi. The current release is configured with modest overclocking as its default. The overclocking settings can be changed in the **config.txt** file found in the boot partition of the CinePI-2K's Micro SD card (after you have successfully flashed it).
**Use additional cooling and/or add a heatsink to your Raspberry Pi for best performance.** If possible, attempt to further push overclocking if your Raspberry Pi and cooling device allow it. Refer to online guides (such as [this one](https://magpi.raspberrypi.org/articles/how-to-overclock-raspberry-pi-4)) on how to properly and safely overclock your Raspberry Pi.
***
### Camera setup
For a visual installation guide, you can watch [this video](https://vimeo.com/517921653). Here are step-by-step instructions:
1. If available, mount your heat sink/cooler on the Raspberry Pi.
2. Attach your camera module with the ribbon band cable to the camera connector on the Raspberry Pi, as explained in the manual of the camera module. Use the tripod screw mount of the camera module to secure it on a tabletop micro tripod, clamp, magic arm or similar.
3. Solder or screw the push button to the loose ends of the twin Dupont cable, or leave the loose ends available to the camera operator. Connect one cable with the Raspberry Pi's GPIO 4 and the other with Ground. A GPIO diagram can be found [here](https://www.raspberrypi.org/documentation/usage/gpio/) in the documentation of the Raspberry Pi project.
4. Screw your lens into the camera module. If you use a c-mount lens, keep the 5mm spacer ring on the camera module. If you use a CS mount (CCTV) lens, screw the spacer ring off the camera module. - In doubt, you can check later whether the lens will be able to focus to infinity, and remove or reattach the ring accordingly.
5. Put the Micro SD card that you flashed with the CinePI-2K software into the Raspberry Pi's Micro SD card slot.
6. Connect your HDMI monitor to the Raspberry Pi. (It doesn't matter to which of the two Micro HDMI ports.)
7. Optionally: connect your USB SSD drive to one of the Raspberry Pi's USB-A ports. (You can also do this later after CinePI-2K has booted.)
### First boot
- Switch on the monitor first.
- Power up the Raspberry Pi by attaching it to USB power.
- About 5-10 seconds later, you should be greeted with the CinePI-2K splash screen. Boot-up time can take another 30-60 seconds. Be patient.
- After the Raspberry Pi has fully booted up, you should see a live view of what your camera can see.
(The aim is optimize boot time in the future to under 10 seconds.)
### Troubleshooting
- If the camera image stays black even after waiting for a longer time, while you see the CinePI-2K's control display (showing ISO, shutter angle, system temperature etc.), make sure that the lens cap of your lens is off.
- If the image is still dark, point the camera to a light source, respectively a brighter lit scene, or increase ISO with the smartphone app (see section _Usage_).
- If your lens doesn't focus, but you only see a blurred-out image, either remove or (if you've already removed it) reattach the C-mount adapter screw mount ring that came with your Raspberry Pi's High Quality Camera module.
- If the camera display is shifted and partly cut off, switch off the monitor and switch it on again (while leaving the CinePI-2K running).
***
## Usage
In addition to the live view you will see a number of other settings/parameters that are updated live according to state of the camera.
- The bottom left shows a live reading of the remaining / total disk space of your attached media.
- The bottom middle is live timecode indicator to show how long your recording is.
- The top right shows both the system temperature and CPU usage statistics.
When you attach a USB 3.x SSD drive to the USB 3 slot of the Raspberry Pi, the disk will automatically be mounted and be ready for recording. (You will see the disk space in the bottom left being updated after your disk has been attached. If it indicates disk space that does not match the actual capacity of the drive you attached, then there might have been a mounting error. Re-attach the disk in this case.)
To trigger recording, press the button or - if you didn't install a button - briefly short-circuit the two cable ends (connected to GPIO 4 and ground, as described in the section _Camera Preparation_). Video recordings can only be made onto an external disk attached via USB 3.x.
With the smartphone app (see section _Installation_), you can currently control the following parameters of the CinePI-2K:
- Frame Rate ( 5-50fps @ 2028x1080 or 5-40fps @ 2028x1520 )
- Shutter Angle
- ISO
- Resolution
***
## Lens guide
### CS mount vs. c-mount
The Raspberry High Quality Camera module supports two types of lenses:
1. CS mount (a standard for CCTV cameras)
2. c-mount (an older standard for 8mm and 16mm film cameras as well as for CCTV video cameras).
Both are screw mounts with identical diameters and mechanics. C-mount and CS mount lenses are indistinguishable from each other unless they have been labeled. The only difference between the two mounts is that CS mount has a shorter flange focal distance (i.e. a shorter distance between lens and sensor) of 12.526 mm than c-mount (17.526 mm). The black adapter ring included with the Raspberry Pi's High Quality Camera module serves as a 5mm spacer to make c-mount lenses fit the camera and have them correctly focus to infinity.
The Raspberry Pi Foundation sells inexpensive 6mm and 16mm CS mount lenses for the High Quality Camera module, which act as wide-angle and moderate tele lenses respectively. On internet marketplaces, you can easily find other CS mount and c-mount lenses, including vintage c-mount lenses for 8mm and 16mm cameras. As a rule of thumb, modern CS mount lenses will give your footage a high contrast video look, old c-mount lenses a softer and more filmic look. (Note: vintage film camera lenses can be pricey collectibles. It often makes more sense to look for defect old film cameras that include suitable - removable - lenses.)
Modern, high-resolution lenses are also more likely to provoke aliasing and moiré artefacts on the CinePi's recorded footage while lower-resolution vintage soften the image and thus prevent moiré.
### Sensor coverage and focal lengths
The Raspberry Pi High Quality Camera module uses a 1/2.3" sensor with a size of 7.564 * 5.476 mm. This means that CCTV lenses made for 1/2" sensors will cover the camera image without vignetting (i.e. without black corners).
In analog film terminology, the CinePi's sensor size of 7.564 * 5.476 mm sit right in between Super 8 (5.79 * 4,01 mm) and 16mm (10.26 * 7.49 mm) and is best comparable to Pathé's 9.5mm film format (8.2 * 6.15 mm).
16mm c-mount film lenses will therefore always cover the CinePi sensor without issues. According to our experience, Super 8 c-mount zooms can vignette at wide-angle settings. Adapted d-mount 8mm prime lenses (see next section) however tend to cover the sensor. (This also includes Kern's c-mount lenses for the Bolex H8 camera. They have a shorter flange focal distance than standard c-mount and can screwed on the CinePI without the c-mount spacer ring.)
Here's an overview of focal lengths for the CinePi, in comparison to common focal lengths for 35mm stills/full frame cameras:
| | super wide-angle | standard wide-angle | slight wide-angle | normal | portrait tele | standard tele | super tele |
|---------------------|---------------------|---------------------|---------------------|-------------------|----------|---------------|---------------|
| CinePi | 5 mm | 6 mm | 7 mm | 10.5 mm | 18 mm | 21 mm | 38mm
| 35mm full frame photo camera (for comparison) | 24 mm | 28 mm | 35 mm | 50 mm | 85 mm | 100 mm | 180 mm
### Adapting other lens mounts
D-mount lenses for Regular 8mm cameras (i.e. the older, 8mm reel-to-reel format with an image size of 4.5 * 3.3 mm that preceded Super 8) can be used on the CinePi with the help of a d-mount to c-mount adapter ring (manufactured by [Fotodiox](https://fotodioxpro.com/products/d-c-p)). Since d-mount has almost the same flange focal distance as CS mount (12.29 mm vs. 12.526 mm), such an adapted lens can be directly screwed onto the camera.
In the past, a number of lens mount adapters for common 35mm photo camera bayonets (Leica, Nikon F, M42, Minolta etc.) to c-mount were produced. These adapters can be used for mounting older manual photo camera lenses to the CinePi. However, the typical focal lengths of these lenses will make turn them into extreme tele focal lengths on the camera.
### Flange focal distance / back focus calibration
The thin, black, jagged metal rotating ring behind the lens mount is for fine-tuning the flange focal distance (respectively back focus) of any lens screwed onto the High Quality Camera module. This is a very useful feature of the camera module and particularly important for using 8 and 16mm parfocal film camera zoom lenses with the CinePi. Parfocality means that a zoom lens stays in focus when being zoomed in and out. (Most photo camera and cheaper CCTV zoom lenses aren't parfocal and lose focus while zooming.)
The best way to calibrate the back focus for a lens is to set its focus to infinity, point it at a far away object (such as a landmark on the horizon) and turn the back focus adjustment ring until the lens perfectly reaches infinity focus.
To set correct back focus for a parfocal zoom lens, the lens should first be calibrated to infnity as described above, then be focused onto a nearby object (in ca. 1-2m meters distance), zoomed in and out while fine-tuning back focus until the object stays in focus.
***
## Rigging
[Information on housings for the CinePI-2k will be added.]
If you use a heavy lens, such as a vintage c-mount zoom lens, support its weight with an extra holder underneath the lens barrel. You may consider putting the CinePI-2K on a video camera rig with 15mm/8inch rods and use a compatible lens support.
***
## Quirks
- Bugs, bugs, bugs....(likely to be lots of other issues I've completely missed, please be ready to document/track these for them to be addressed.)
***
## Developers
The source can be accessed straight from the Pi via SSH using the credentials:
-user: pi
-pwd: cinemapi
***
Hopefully you too will be able to get your own CinePI-2K up and running and capture some exceptional footage with this low-cost setup! (I would love to see the footage you capture so don't be afraid to share!)
Track bugs in the issues section. I expect there will be lots at the start.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 379 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 554 KiB

30
docs/images/BuildGuide.md Normal file
View File

@ -0,0 +1,30 @@
| Item | Quantity | Link | Price |
|----------------------------------------|----------|--------------------------------------------------------------------------------------------|---------|
| Raspbery Pi 2/4/8GB | 1 | https://www.digikey.com/en/products/detail/raspberry-pi/RASPBERRY-PI-4-MODEL-B-8G/12159401 | $35-$75 |
| Raspberry Pi HQ Camera | 1 | https://www.digikey.com/en/products/detail/raspberry-pi/SC0818/12339164 | $50.00 |
| Pimoroni Hyperpixel Square 4.0" | 1 | https://www.digikey.com/en/products/detail/pimoroni-ltd/PIM470/10329005 | $76.50 |
| Zero2GoOmini R2 | 1 | https://www.digikey.com/en/products/detail/pimoroni-ltd/zero2go-omini-r2/15851372 | $22.00 |
| | | | |
| PCF8574 | 1 | https://amz.run/6bhj | $1.57 |
| PCF8523 | 1 | https://www.digikey.ca/en/products/detail/adafruit-industries-llc/3295/6238007 | $6.95 |
| CR1220 | 1 | https://amz.run/6bhs | N/A |
| | | | |
| Dupont Wires | | https://www.aliexpress.com/item/1005002000655439.html | |
| 40-pin FFC Cable | 1 | https://www.digikey.ca/en/products/detail/adafruit-industries-llc/4933/14291405 | |
| 40-pin GPIO FFC Extender Angled Male | 1 | https://www.digikey.ca/en/products/detail/adafruit-industries-llc/4904/14205155 | |
| 40-pin GPIO FFC Extender Angled Female | 1 | https://www.digikey.ca/en/products/detail/adafruit-industries-llc/4905/14205159 | |
| SparkFun QWIC Breakout | 2 | https://www.digikey.ca/en/products/detail/sparkfun-electronics/DEV-14495/7942483 | |
| QWIC Cables | | https://www.digikey.ca/en/products/detail/sparkfun-electronics/PRT-17260/13629028 | |
| | | | |
| Notcua NF-A4x10 5V 3-pin | 1 | https://amz.run/6bht | |
| 12mm Blue LED Button | 1 | https://www.aliexpress.com/item/33014419878.html | |
| 12mm Red LED Button | 1 | https://www.aliexpress.com/item/33014419878.html | |
| 7-pin LEMO Female | 1 | https://www.aliexpress.com/item/1005004949203075.html | |
| | | | |
| NCR18650B | 4 | https://www.18650batterystore.com/en-ca/products/panasonic-ncr18650b | |
| Micro JST connector/cable | | https://www.aliexpress.com/item/32704408939.html | |
| PVC Shrink | | | |
| 4S BMS | 1 | https://www.aliexpress.com/item/1005005389852465.html | |
| | | | |
| | | | |
| | | | |

BIN
docs/images/hero-banner.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 665 KiB

File diff suppressed because it is too large Load Diff

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

View File

@ -1,7 +0,0 @@
# CinePI Case Design
 
Documentation Coming soon.

File diff suppressed because it is too large Load Diff

1
software/cinepi-raw Submodule

@ -0,0 +1 @@
Subproject commit 818064ec48e56f4a2ce74f9910bf3ab2fcf45b97

1
software/libcamera Submodule

@ -0,0 +1 @@
Subproject commit e3111091e0c4eed5611174beb3169af36e287674

@ -0,0 +1 @@
Subproject commit 5ff345af97cbb7520a697010157017705d27111e