raspi/userland
1
0
Fork 0
mirror of https://github.com/raspberrypi/userland.git synced 2025-12-06 04:49:12 +00:00
Code Issues Projects Releases Wiki Activity

Add man-pages for most commands

Browse Source 
I've spent a little time going through the excellent raspberry pi
documentation site in order to build some man-pages for most of the
utilities in the suite. Note that not all utilities are covered here
(notably vchiq_test, mmal_vc_diag are missing) but I think it covers the
most commonly used utilities.

I've also included some auxilliary man-pages (in section 7) for
information relevant to utilities like vcmailbox (covering things like
the mailbox info from the wiki-page, and the OTP registers from the
documentation site).
This commit is contained in:
Dave Jones
2020-11-30 13:58:45 +00:00
committed by Phil Elwell
parent 3fd8527eef
commit 45a0022ac6
20 changed files with 5734 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
host_applications/linux/apps/dtmerge/CMakeLists.txt
View File

@@ -18,3 +18,4 @@ add_executable(dtmerge dtmerge.c)
target_link_libraries(dtmerge dtovl)
install(TARGETS dtmerge RUNTIME DESTINATION bin)
install(FILES dtmerge.1 DESTINATION man/man1)

72
host_applications/linux/apps/dtmerge/dtmerge.1 Normal file
View File

@@ -0,0 +1,72 @@
.TH DTMERGE 1
.
.SH NAME
dtmerge \- merge an overlay or parameters into a base device-tree
.
.
.SH SYNOPSIS
.SY dtmerge
.OP \-d
.I base-dtb
.I merged-dtb
.I overlay-dtb
.RI [ param=val \|.\|.\|.]
.YS
.
.SY dtmerge
.B \-h
.YS
.
.
.SH DESCRIPTION
.B dtmerge
is a command line utility for merging overlays and/or device-tree parameters
with a base device-tree.
See
.B [DTREE]
for more information.
.
.PP
The base device-tree (in dtb format) is always specified as the first
(non-option) argument.
The second argument is the output filename, which will also be in dtb format.
The third argument provides the name of the overlay to merge into the base
tree.
If this is "-" then no overlay is used and the utility will simply customize
the base tree with any parameters given.
.
.
.SH OPTIONS
.
.TP
.BR \-d
Show debug output during operation.
.
.TP
.BR \-h
Displays help on the application.
.
.
.SH EXAMPLES
.
.TP
.B dtmerge /boot/bcm2711-rpi-4-b.dtb out.dtb - spi=on i2c=on
Produce a device-tree for the Raspberry Pi 4 in "out.dtb" which has the SPI and
I2C interfaces activated.
.
.TP
.B dtmerge /boot/bcm2710-rpi-3-b-plus.dtb out.dtb /boot/overlays/gpio-shutdown.dtbo
Produce a device-tree for the Raspberry Pi 3+ in "out.dtb" which includes the
GPIO shutdown overlay (with all parameters set to their default).
.
.
.SH SEE ALSO
.BR dtoverlay (1),
.BR dtparam (1),
.B [DTREE]
.
.
.SH REFERENCES
.TP
.B [DTREE]
https://www.raspberrypi.org/documentation/configuration/device-tree.md

2
host_applications/linux/apps/dtoverlay/CMakeLists.txt
View File

@@ -17,9 +17,11 @@ include_directories (
add_executable(dtoverlay dtoverlay_main.c utils.c)
target_link_libraries(dtoverlay dtovl)
install(TARGETS dtoverlay RUNTIME DESTINATION bin)
install(FILES dtoverlay.1 DESTINATION man/man1)
add_custom_command(TARGET dtoverlay POST_BUILD COMMAND ln;-sf;dtoverlay;dtparam)
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/dtparam DESTINATION bin)
install(FILES dtparam.1 DESTINATION man/man1)
set(DTOVERLAY_SCRIPTS dtoverlay-pre dtoverlay-post)
install(PROGRAMS ${DTOVERLAY_SCRIPTS} DESTINATION bin)

153
host_applications/linux/apps/dtoverlay/dtoverlay.1 Normal file
View File

@@ -0,0 +1,153 @@
.TH DTOVERLAY 1
.
.SH NAME
dtoverlay \- load a device-tree overlay
.
.
.SH SYNOPSIS
.SY dtoverlay
.OP \-d dir
.OP \-p string
.OP \-v
.OP \-D
.OP \-r
.OP \-R
.OP \-l
.OP \-a
.RI [ overlay " [" param=val \|.\|.\|.]]
.YS
.
.SY dtoverlay
.B \-h
.RI [ overlay " [" param ]]
.YS
.
.
.SH DESCRIPTION
.B dtoverlay
is a command line utility for manipulating the system's runtime device-tree by
adding or removing overlays.
It can also customize the base device-tree or overlays by setting parameters
within them.
See
.B [DTREE]
for more information.
.
.PP
By default, without the
.B -r
or
.B -R
options, the application adds the specified overlay. Manipulation of
active device-tree overlays usually requires root privileges.
.
.
.SH OPTIONS
.
.TP
.BR \-a
Lists all defined device-tree overlays, placing a "*" next to those that are
currently loaded.
.
.TP
.BR \-d " \fIdir\fR"
Specifies an alternate location path from which to load overlays. The utility
defaults to "/boot/overlays" or "/flash/overlays".
.
.TP
.BR \-D
Dry-run; prepares the specified overlay but doesn't apply it. The resulting
prepared overlay is saved as "dry-run.dtbo".
.
.TP
.BR \-h [\fIoverlay\fR] [\fIparam\fR]
If given without
.I overlay
or
.I param
displays help on the application overall. If
.I overlay
is specified, prints help on that overlay. Finally, if
.I param
is also specified, prints help on that parameter of the overlay. To query
parameters on the base overlay, specify "dtparam" as the
.IR overlay .
.
.TP
.BR \-l
Lists all currently loaded device-tree overlays, in the order they were loaded.
This also specifies the index of each overlay.
.
.TP
.BR \-p " \fIstring\fR"
Override the platform's "compatible" string, normally read from
"/proc/device-tree/compatible". This is used with the overlay map to determine
which platform-specific overlay to read (if necessary).
.
.TP
.BR \-r
Remove overlay. With this option, the utility will remove the specified
overlay. If no overlay is given, the last overlay loaded will be removed.
Overlays can be specified by name or by index.
.
.TP
.BR \-R
Remove the specified overlay, and all subsequent overlays that were loaded
after it. If no overlay is given, all overlays will be removed. Overlays can
be specified by name or by index.
.
.TP
.BR \-v
Verbose operation; the utility will produce more output.
.
.
.SH EXAMPLES
.
.TP
.B sudo dtoverlay w1-gpio
Load the w1-gpio overlay (to enable Dallas 1-Wire on GPIO4). Note that root
privileges are usually required for manipulating the device-tree overlays
(hence, sudo in the example).
.
.TP
.B dtoverlay -l
Show the loaded overlays.
.
.TP
.B sudo dtoverlay -r
Remove the last loaded overlay.
.
.TP
.B sudo dtoverlay gpio-shutdown gpio_pin=7 active_low=0 gpio_pull=down
Load the gpio-shutdown overlay specifying that it should pull GPIO7 down and
monitor it for a rising edge to initiate shutdown.
.
.TP
.B dtoverlay -h gpio-shutdown
Display help for the gpio-shutdown overlay
.
.TP
.B sudo dtoverlay -r gpio-shutdown
Remove the gpio-shutdown overlay, wherever it is in the load order.
.
.
.SH HOOKS
.B dtoverlay
attempts to call two executables (shell scripts by default) during its
operation:
.B dtoverlay-pre
prior to making device-tree modifications, and
.B dtoverlay-post
afterwards. Each executable is optional and will be ignored if not present.
.
.
.SH SEE ALSO
.BR dtparam (1),
.BR dtmerge (1),
.B [DTREE]
.
.
.SH REFERENCES
.TP
.B [DTREE]
https://www.raspberrypi.org/documentation/configuration/device-tree.md

66
host_applications/linux/apps/dtoverlay/dtparam.1 Normal file
View File

@@ -0,0 +1,66 @@
.TH DTPARAM 1
.
.SH NAME
dtparam \- mainpulate parameters of the base device-tree
.
.
.SH SYNOPSIS
.SY dtparam
.RI [ param=val \|.\|.\|.]
.YS
.
.SY dtparam
.B \-h
.RI [ param ]
.YS
.
.
.SH DESCRIPTION
.B dtparam
is a command line utility for manipulating the base device-tree's parameters.
For example, it can be used to enable the SPI or I2C interfaces at runtime
without rebooting.
If
.B dtparam
is run without any argument, it prints the names of all base device-tree
parameters and their description.
.
.
.SH OPTIONS
.
.TP
.BR \-h " [\fIparam\fR]"
If given without
.I param
displays help on the application overall. If
.I param
is specified, prints help about that parameter in the base device-tree.
.
.
.SH EXAMPLES
.
.TP
.B sudo dtparam spi=on
Enable the SPI interface on the GPIO header. Note that root privileges are
usually required for manipulating the base device-tree (hence, sudo in the
example).
.
.TP
.B dtparam -h spi
Print help about the "spi" parameter.
.
.TP
.B sudo dtparam audio=off
Disable the audio output.
.
.
.SH SEE ALSO
.BR dtoverlay (1),
.BR dtmerge (1),
.B [DTREE]
.
.
.SH REFERENCES
.TP
.B [DTREE]
https://www.raspberrypi.org/documentation/configuration/device-tree.md

2
host_applications/linux/apps/gencmd/CMakeLists.txt
View File

@@ -17,4 +17,4 @@ include_directories( ../../../..
add_executable(vcgencmd gencmd.c)
target_link_libraries(vcgencmd vcos vchiq_arm vchostif)
install(TARGETS vcgencmd RUNTIME DESTINATION bin)
install(FILES vcgencmd.1 DESTINATION man/man1)

303
host_applications/linux/apps/gencmd/vcgencmd.1 Normal file
View File

@@ -0,0 +1,303 @@
.TH VCGENCMD 1
.
.SH NAME
vcgencmd \- query the VideoCore for information
.
.
.SH SYNOPSIS
.SY vcgencmd
.OP \-t
.IR command \ [ params ]
.YS
.
.SY vcgencmd
.B \-h
.SY vcgencmd
.B \-\-help
.YS
.
.
.SH DESCRIPTION
.B vcgencmd
is a command line utility that can get various pieces of information
from the VideoCore GPU on the Raspberry Pi.
.
.
.SH OPTIONS
.TP
.B \-t
Time how long the command takes to complete
.
.TP
.BR \-h ", " \-\-help
Show this information
.
.
.SH COMMANDS
To get a list of all the commands that
.B vcgencmd
supports, type
.IR "vcgencmd\ commands" .
Some of the more useful commands are described below.
.
.TP
.BI vcos \ sub-command
The
.B vcos
command has a number of sub-commands:
.RS
.TP
.B version
Displays the build date and version of the firmware on the VideoCore.
.TP
.B log status
Displays the error log status of the various VideoCore software areas.
.RE
.
.TP
.B version
Displays the build date and version of the firmware on the VideoCore.
.
.TP
.B get_camera
Displays the enabled and detected state of the official camera. 1 means yes, 0
means no. Whilst all firmware (except cutdown versions) will support the camera,
this support needs to be enabled by using the
.I start_x
boot option
.BR [BOOT] .
.
.TP
.B get_throttled
Returns the throttled state of the system. This is a bit pattern - a bit being
set indicates the following meanings:
.TS
tab(|);
l l .
Bit|Meaning
\_|\_
.T&
n l .
0|Under-voltage detected
1|Arm frequency capped
2|Currently throttled
3|Soft temperature limit active
16|Under-voltage has occurred
17|Arm frequency capping has occurred
18|Throttling has occurred
19|Soft temperature limit has occurred
.TE
.IP
A value of zero indicates that none of the above conditions is true.
.IP
To find if one of these bits has been set, convert the value returned to binary,
then number each bit along the top. You can then see which bits are set. For
example:
.IP
.EX
0x50000 = 0101 0000 0000 0000 0000
.EE
.IP
Adding the bit numbers along the top we get:
.TS
tab( );
n n n n n n n n n n n n n n n n n n n .
19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1
0 1 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
.TE
.IP
From this we can see that bits 18 and 16 are set, indicating that the Pi has
previously been throttled due to under-voltage, but is not currently throttled
for any reason.
.
.TP
.B measure_temp
Returns the temperature of the SoC as measured by the on-board temperature
sensor.
.
.TP
.BI measure_clock \ clock
This returns the current frequency of the specified clock. The options are:
.TS
tab(|);
l l .
Clock|Description
\_|\_
arm|ARM cores
core|VC4 scaler cores
h264|H.264 block
isp|Image Signal Processor
v3d|3D block
uart|UART
pwm|PWM block (analog audio output)
emmc|SD card interface
pixel|Pixel valve
vec|Analog video encoder
hdmi|HDMI
dpi|Display Peripheral Interface
.TE
.IP
For example,
.IR "vcgencmd measure_clock arm" .
.
.TP
.BI measure_volts \ block
Displays the current voltages used by the specific block.
.TS
tab(|);
l l .
Block|Description
\_|\_
core|VC4 core voltage
sdram_c|
sdram_i|
sdram_p|
.TE
.
.TP
.B otp_dump
Displays the content of the One Time Programmable (OTP) memory, which is part
of the SoC. These are 32 bit values, indexed from 8 to 64. See the
.BR raspi-otp (7)
for more details.
.
.TP
.BI get_mem \ type
Reports on the amount of memory allocated to the ARM cores with
.I vcgencmd get_mem arm
or the VC4 with
.IR "vcgencmd get_mem gpu" .
.IP
.B Note:
On a Raspberry Pi 4 with greater than 1GB of RAM, the
.I arm
option is inaccurate.
This is because the GPU firmware which implements this command is only aware of
the first gigabyte of RAM on the system, so the
.I arm
setting will always return
1GB minus the
.I gpu
memory value. To get an accurate report of the amount of ARM
memory, use one of the standard Linux commands, such as
.I free
or
.IR "cat /proc/meminfo" .
.
.TP
.BI codec_enabled \ type
Reports whether the specified CODEC type is enabled. Possible options for type
are AGIF, FLAC, H263, H264, MJPA, MJPB, MJPG, MPG2, MPG4, MVC0, PCM, THRA,
VORB, VP6, VP8, WMV9, WVC1.
.IP
MPG2, WMV9, and WVC1 currently require a paid for licence (see the
.B [FAQ]
for more info), except on the Pi4, where these hardware codecs are disabled in
preference to software decoding, which requires no licence. Note that because
the H265 hardware block on the Raspberry Pi4 is not part of the VideoCore GPU,
its status is not accessed via this command.
.
.TP
.BI get_config \ type|name
This returns all the configuration items of the specified type that have been
set in config.txt, or a single configuration item. Possible values for type
parameter are
.IR int ", " str ", "
or simply use the name of the configuration item.
.
.TP
.B get_lcd_info
Displays the resolution and colour depth of any attached display.
.
.TP
.B mem_oom
Displays statistics on any Out Of Memory events occuring in the VC4 memory
space.
.
.TP
.B mem_reloc_stats
Displays statistics from the relocatable memory allocator on the VC4.
.
.TP
.B read_ring_osc
Returns the curent speed voltage and temperature of the ring oscillator.
.
.TP
.B hdmi_timings
Displays the current HDMI settings timings. See
.B [VIDEO]
for details of the values returned.
.
.TP
.B dispmanx_list
Dump a list of all dispmanx items currently being displayed.
.
.TP
.BI display_power \ 0|1|-1
.TQ
.BI display_power " 0|1|-1 display"
Show current display power state, or set the display power state.
.I vcgencmd display_power 0
will turn off power to the current display.
.I vcgencmd display_power 1
will turn on power to the display. If no parameter is set, this will display
the current power state. The final parameter is an optional display ID, as
returned by
.I tvservice -l
or from the table below, which allows a specific display to be turned on or
off.
.IP
.I vcgencmd display_power 0 7
will turn off power to display ID 7, which is HDMI 1 on a Raspberry Pi 4.
.TS
tab(|);
l l .
Display|ID
\_|\_
.T&
l n .
Main LCD|0
Secondary LCD|1
HDMI 0|2
Composite|3
HDMI 1|7
.TE
.IP
To determine if a specific display ID is on or off, use -1 as the first
parameter.
.IP
.I vcgencmd display_power -1 7
will return 0 if display ID 7 is off, 1 if display ID 7 is on, or -1 if display
ID 7 is in an unknown state, for example undetected.
.
.
.SH EXIT STATUS
.
.IP 0
Command completed successfully
.IP -1
Problem with VHCI
.IP -2
VideoCore returned an error
.
.
.SH SEE ALSO
.B [SOURCE]
.
.
.SH REFERENCES
.TP
.B [BOOT]
https://www.raspberrypi.org/\:documentation/\:configuration/\:config-txt/\:boot.md
.
.TP
.B [FAQ]
https://www.raspberrypi.org/\:documentation/\:faqs/\:README.md
.
.TP
.B [SOURCE]
https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:vcgencmd.md
.
.TP
.B [VIDEO]
https://www.raspberrypi.org/\:documentation/\:configuration/\:config-txt/\:video.md

2
host_applications/linux/apps/raspicam/CMakeLists.txt
View File

@@ -67,3 +67,5 @@ target_link_libraries(raspivid ${MMAL_LIBS} vcos bcm_host m)
target_link_libraries(raspividyuv ${MMAL_LIBS} vcos bcm_host m)
install(TARGETS raspistill raspiyuv raspivid raspividyuv RUNTIME DESTINATION bin)
install(FILES raspistill.1 raspiyuv.1 raspivid.1 raspividyuv.1 DESTINATION man/man1)
install(FILES raspicam.7 DESTINATION man/man7)

691
host_applications/linux/apps/raspicam/raspicam.7 Normal file
View File

@@ -0,0 +1,691 @@
.TH RASPICAM 7
.
.SH NAME
raspicam \- the Raspberry Pi Camera Module and its utilities
.
.
.SH DESCRIPTION
.
There are four applications provided:
.BR raspistill (1),
.BR raspivid (1),
.BR raspiyuv (1)
and
.BR raspividyuv (1).
.BR raspistill (1)
and
.BR raspiyuv (1)
are very similar and are intended for capturing images;
.BR raspivid (1)
and
.BR raspvidyuv (1)
are for recording video.
The utilities share many common options, which are documented in the sections
.BR "HARDWARE OPTIONS" ,
.BR "PREVIEW OPTIONS" ,
.BR "IMAGE OPTIONS" ,
and
.BR "STEREOSCOPIC (3D) OPTIONS"
below. Within each section, options are listed alphabetically (by the
long-option's title).
.PP
All the applications are driven from the command line, and written to take
advantage of the MMAL API which runs over OpenMAX. The MMAL API provides an
easier to use system than that presented by OpenMAX. Note that MMAL is a
Broadcom-specific API used only on VideoCore 4 systems.
.PP
The applications use up to four OpenMAX (MMAL) components: camera, preview,
encoder, and null_sink. All applications use the camera component;
.BR raspistill (1)
uses the Image Encode component;
.BR raspivid (1)
uses the Video Encode component; and
.BR raspiyuv (1)
and
.BR raspividyuv (1)
don't use an encoder, sending their YUV or RGB output directly from the
camera component to file.
.PP
The preview display is optional, but can be used full-screen or directed to a
specific rectangular area on the display. If preview is disabled, the null_sink
component is used to 'absorb' the preview frames. The camera must produce
preview frames even if these aren't required for display, as they're used for
calculating exposure and white balance settings.
.PP
In addition, it's possible to omit the filename option (in which case the
preview is displayed but no file is written), or to redirect all output to
stdout.
.
.
.SH GETTING STARTED
.
.B Warning:
Cameras are sensitive to static. Earth yourself prior to handling the PCB. A
sink tap or similar should suffice if you don’t have an earthing strap.
.PP
The camera board attaches to the Raspberry Pi via a 15-way ribbon cable. There
are only two connections to make: the ribbon cable needs to be attached to the
camera PCB, and to the Raspberry Pi itself. You need to get the cable the right
way round, or the camera will not work. On the camera PCB, the blue backing on
the cable should face away from the PCB, and on the Raspberry Pi it should face
towards the Ethernet connection (or where the Ethernet connector would be if
you're using a model A+).
.PP
Although the connectors on the PCB and the Pi are different, they work in a
similar way. On the Raspberry Pi itself, pull up the tabs on each end of the
connector. It should slide up easily, and be able to pivot around slightly.
Fully insert the ribbon cable into the slot, ensuring it is set straight, then
gently press down the tabs to clip it into place. The camera PCB connector also
requires you to pull the tabs away from the board, gently insert the cable,
then push the tabs back. The PCB connector can be a little more awkward than
the one on the Pi itself.
.
.
.SH TROUBLESHOOTING
.
If the Camera Module isn't working correctly, there are number of things to
try:
.IP \(bu 2
Is the ribbon cable attached to the Camera Serial Interface (CSI), not the
Display Serial Interface (DSI)? The ribbon connector will fit into either port.
The Camera port is located near the HDMI connector.
.
.IP \(bu
Are the ribbon connectors all firmly seated, and are they the right way round?
They must be straight in their sockets.
.
.IP \(bu
Is the Camera Module connector, between the smaller black Camera Module itself
and the PCB, firmly attached? Sometimes this connection can come loose during
transit or when putting the Camera Module in a case. Using a fingernail, flip
up the connector on the PCB, then reconnect it with gentle pressure. It engages
with a very slight click. Don't force it; if it doesn't engage, it's probably
slightly misaligned.
.
.IP \(bu
Have
.I sudo apt update
and
.I sudo apt full-upgrade
been run?
.
.IP \(bu
Is
.I start_x=1
present in the \(lqconfig.txt\(rq boot configuration?
.
.IP \(bu
Is your power supply sufficient? The Camera Module adds about 200-250mA to the
power requirements of your Raspberry Pi.
.
.PP
Try the following in response to specific error messages:
.
.TP
.B Error : raspistill/raspivid command not found
This probably means your update/upgrade failed in some way. Try it again.
.
.TP
.B Error : ENOMEM
The Camera Module is not starting up. Check all connections again.
.
.TP
.B Error : ENOSPC
The Camera Module is probably running out of GPU memory. Check
\(lqconfig.txt\(rq on the boot partition. The
.I gpu_mem
option should be at least 128.
.
.
.SH HARDWARE OPTIONS
.
.TP
.BR \-cs ", " \-\-camselect " \fIcamera\fR"
Selects the camera to use on a multi-camera system (currently only Pi
Compute Modules).
Use 0 or 1.
.
.TP
.BR \-md ", " \-\-mode " \fImode\fR"
Sets a specified sensor mode, disabling the automatic selection.
Possible values depend on the version of the Camera Module being used:
.IP
Version 1.x (OV5647)
.TS
tab(|);
l l l l l l .
Mode|Size|Aspect|Framerates|FOV|Binning
\_|\_|\_|\_|\_|\_
.T&
n c s s s s .
0|--- automatic selection ---
.T&
n l l l l l .
1|1920 x 1080|16:9|1 - 30fps|Partial|None
2|2592 x 1944|4:3|1 - 15fps|Full|None
3|2592 x 1944|4:3|0.1666 - 1fps|Full|None
4|1296 x 972|4:3|1 - 42fps|Full|2 x 2
5|1296 x 730|16:9|1 - 49fps|Full|2 x 2
6|640 x 480|4:3|42.1 - 60fps|Full|2 x 2 + skip
7|640 x 480|4:3|60.1 - 90fps|Full|2 x 2 + skip
.TE
.IP
Version 2.x (IMX219)
.TS
tab(|);
l l l l l l .
Mode|Size|Aspect|Framerates|FOV|Binning
\_|\_|\_|\_|\_|\_
.T&
n c s s s s .
0|--- automatic selection ---
.T&
n l l l l l .
1|1920 x 1080|16:9|0.1 - 30fps|Partial|None
2|3280 x 2464|4:3|0.1 - 15fps|Full|None
3|3280 x 2464|4:3|0.1 - 15fps|Full|None
4|1640 x 1232|4:3|0.1 - 40fps|Full|2 x 2
5|1640 x 922|16:9|0.1 - 40fps|Full|2 x 2
6|1280 x 720|16:9|40 - 90fps|Partial|2 x 2
7|640 x 480|4:3|40 - 200fps*|Partial|2 x 2
.TE
.IP
* For frame rates over 120fps, it is necessary to turn off automatic exposure
and gain control using
.IR "-ex off" .
Doing so should achieve the higher frame rates, but exposure time and gains
will need to be set to fixed values supplied by the user.
.IP
HQ Camera (IMX477)
.TS
tab(|);
l l l l l l .
Mode|Size|Aspect|Framerates|FOV|Binning
\_|\_|\_|\_|\_|\_
.T&
n c s s s s .
0|--- automatic selection ---
.T&
n l l l l l .
1|2028 x 1080|169:90|0.1 - 50fps|Partial|2 x 2
2|2028 x 1520|4:3|0.1 - 50fps|Full|2 x 2
3|4056 x 3040|4:3|0.005 - 10fps|Full|None
4|1012 x 760|4:3|50.1 - 120fps|Full|4 x 4
.TE
.
.TP
.BR \-gps ", " \-\-gpsdexif
Applies real-time EXIF information from any attached GPS dongle (using GSPD) to
the image; requires
.I libgps.so
to be installed.
.
.
.SH PREVIEW OPTIONS
.
.TP
.BR \-dn ", " \-\-dispnum " \fIscreen\fR"
Specifies which display the camera preview should appear on, using dispmanx /
tvservice numbering (see the output of
.I tvservice -l
or the
.I display_power
command under
.BR vcgencmd (1)
for more information).
.
.TP
.BR \-f ", " \-\-fullscreen
Forces the preview window to use the whole screen. Note that the aspect ratio
of the incoming image will be retained, so there may be bars on some edges.
.
.TP
.BR \-n ", " \-\-nopreview
Disables the preview window completely. Note that even though the preview is
disabled, the camera will still be producing frames, so will be using power.
.
.TP
.BR \-op ", " \-\-opacity " \fIvalue\fR"
Sets the opacity of the preview window. 0 = invisible, 255 = fully opaque.
.
.TP
.BR \-p ", " \-\-preview " \fIx,y,w,h\fR"
Allows the user to define the size of the preview window and its location on
the screen. Note this will be superimposed over the top of any other
windows/graphics.
.
.
.SH IMAGE OPTIONS
.
.TP
.BR \-a ", " \-\-annotate " \fIflags|text\fR"
Adds some text and/or metadata to the picture.
.IP
Metadata is indicated using a bitmask notation, so add them together to show
multiple parameters. For example, 12 will show time (4) and date (8), since
4+8=12.
.IP
Text may include date/time placeholders by using the '%' character, as used by
.BR strftime (3).
.RS
.TP
.B \-a 4
Displays the time, "20:09:33"
.TP
.B \-a 8
Displays the date, "10/28/15"
.TP
.B \-a 16
Shutter settings
.TP
.B \-a 32
CAF settings
.TP
.B \-a 64
Gain settings
.TP
.B \-a 128
Lens settings
.TP
.B \-a 256
Motion settings
.TP
.B \-a 512
Frame number
.TP
.B \-a 1024
Black background
.TP
.B \-a "ABC"
Show the specified text, "ABC"
.TP
.B \-a "ABC %Y\-%m\-%d"
Show the specified text, "ABC %Y\-%m\-%d"
.TP
.B \-a 4 \-a "ABC %Y\-%m\-%d %X"
Displays a formatted timestamp, "ABC 2015\-10\-28 20:09:33"
.TP
.B \-a 8 \-a "ABC %Y\-%m\-%d %X"
Also displays a formatted timestamp, "ABC 2015\-10\-28 20:09:33"
.RE
.
.TP
.BR \-ae ", " \-\-annotateex " \fIsize,fg,bg\fR"
Specifies annotation size, text color, and background color. Colors are in
hex YUV format.
Size ranges from 6 - 160; default is 32. Asking for an invalid size should give
you the default.
.IP
For example, to obtain size 32 white text on a black background:
.IP
.EX
-ae 32,0xff,0x808000 -a "Annotation text"
.EE
.IP
Or for size 10 black text on a white background:
.IP
.EX
-ae 10,0x00,0x8080FF -a "Annotation text"
.EE
.
.TP
.BR \-ag ", " \-\-analoggain " \fIvalue\fR"
Sets the analog gain value directly on the sensor (floating point value from
1.0 to 8.0 for the OV5647 sensor on V1 Camera Module, and 1.0 to 12.0 for the
IMX219 sensor on V1 Camera Module and the IMX447 on the HQ Camera).
.
.TP
.BR \-awb ", " \-\-awb " \fImode\fR"
Modes for which color temperature ranges (in Kelvin) are available have these
settings in brackets.
.RS
.TP
.B off
turn off white balance calculation
.TP
.B auto
automatic mode (default)
.TP
.B sun
sunny mode (between 5000K and 6500K)
.TP
.B cloud
cloudy mode (between 6500K and 12000K)
.TP
.B shade
shade mode
.TP
.B tungsten
tungsten lighting mode (between 2500K and 3500K)
.TP
.B fluorescent
fluorescent lighting mode (between 2500K and 4500K)
.TP
.B incandescent
incandescent lighting mode
.TP
.B flash
flash mode
.TP
.B horizon
horizon mode
.TP
.B greyworld
used on the NoIR camera to fix incorrect AWB results due to the lack of the IR
filter
.RE
.IP
Note that not all of these settings may be implemented, depending on camera
type.
.
.TP
.BR \-awbg ", " \-\-awbgains " \fIblue,red\fR"
Sets blue and red gains (as floating point numbers) to be applied when
.I \-awb off
is set e.g.
.I \-awbg 1.5,1.2
.
.TP
.BR \-br ", " \-\-brightness " \fIvalue\fR"
Sets the brightness of the image, from 0 to 100. 50 is the default.
.
.TP
.BR \-cfx ", " \-\-colfx " \fIu:v\fR"
The supplied U and V parameters (range 0 - 255) are applied to the U and Y
channels of the image. For example,
.I \-\-colfx 128:128
should result in a monochrome image.
.
.TP
.BR \-co ", " \-\-contrast " \fIvalue\fR"
Sets the contrast of the image, from -100 to 100. 0 is the default.
.
.TP
.BR \-dg ", " \-\-digitalgain " \fIvalue\fR"
Sets the digital gain value applied by the ISP (floating point value from 1.0
to 64.0, but values over about 4.0 will produce overexposed images).
.
.TP
.BR \-drc ", " \-\-drc " \fIvalue\fR"
Dynamic range control (DRC) changes the images by increasing the range of dark
areas, and decreasing the brighter areas. This can improve the image in low
light areas. Valid values are
.IR off " (default), " low ", " med ", or " high.
.
.TP
.BR \-ev ", " \-\-ev " \fIvalue\fR"
Sets the exposure value compensation, from -10 to 10. 0 is the default.
.
.TP
.BR \-ex ", " \-\-exposure " \fImode\fR"
Sets the exposure mode of the camera. Possible options are:
.RS
.TP
.B auto
use automatic exposure mode (default)
.TP
.B night
select setting for night shooting
.TP
.B nightpreview
<undocumented>
.TP
.B backlight
select setting for backlit subject
.TP
.B spotlight
<undocumented>
.TP
.B sports
select setting for sports (fast shutter etc.)
.TP
.B snow
select setting optimized for snowy scenery
.TP
.B beach
select setting optimized for beach
.TP
.B verylong
select setting for long exposures
.TP
.B fixedfps
constrain fps to a fixed value
.TP
.B antishake
select "antishake" mode
.TP
.B fireworks
select setting optimized for fireworks
.RE
.IP
Note that not all of these settings may be implemented, depending on camera
tuning.
.
.TP
.BR \-fli ", " \-\-flicker " \fImode\fR"
Set a mode to compensate for lights flickering at the mains frequency, which
can be seen as a dark horizontal band across an image. Flicker avoidance locks
the exposure time to a multiple of the mains flicker frequency (8.33ms for
60Hz, or 10ms for 50Hz). This means that images can be noisier as the control
algorithm has to increase the gain instead of exposure time should it wish for
an intermediate exposure value.
.I auto
can be confused by external factors, therefore it is preferable to leave this
setting off unless actually required.
.IP
Possible options are:
.RS
.TP
.B off
turn off flicker avoidance
.TP
.B auto
automatically detect mains frequency
.TP
.B 50hz
set avoidance at 50Hz
.TP
.B 60hz
set avoidance at 60Hz
.RE
.
.TP
.BR \-hf ", " \-\-hflip
Flips the preview and saved image horizontally.
.
.TP
.BR \-ifx ", " \-\-imxfx " \fIeffect\fR"
Set an effect to be applied to the image:
.RS
.TP
.B none
no effect (default)
.TP
.B negative
invert the image colors
.TP
.B solarise
solarize the image
.TP
.B posterise
posterize the image
.TP
.B whiteboard
whiteboard effect
.TP
.B blackboard
blackboard effect
.TP
.B sketch
sketch effect
.TP
.B denoise
denoise the image
.TP
.B emboss
emboss the image
.TP
.B oilpaint
oil paint effect
.TP
.B hatch
hatch sketch effect
.TP
.B gpen
graphite sketch effect
.TP
.B pastel
pastel effect
.TP
.B watercolour
watercolor effect
.TP
.B film
film grain effect
.TP
.B blur
blur the image
.TP
.B saturation
saturate the image color
.TP
.B colourswap
not fully implemented
.TP
.B washedout
not fully implemented
.TP
.B colourpoint
not fully implemented
.TP
.B colourbalance
not fully implemented
.TP
.B cartoon
not fully implemented
.RE
.IP
Note that not all of these settings may be available in all circumstances.
.
.TP
.BR \-ISO ", " \-\-ISO " \fIvalue\fR"
Sets the ISO to be used for captures, from 100 to 800. The default is
automatic.
.
.TP
.BR \-mm ", " \-\-metering " \fImode\fR"
Specify the metering mode used for the preview and capture:
.RS
.TP
.B average
average the whole frame for metering
.TP
.B spot
spot metering in the center of the frame
.TP
.B backlit
assume a backlit image
.TP
.B matrix
matrix metering
.RE
.
.TP
.BR \-roi ", " \-\-roi " \fIx,y,w,h\fR"
Allows the specification of the area of the sensor to be used as the source for
the preview and capture. This is defined as x,y for the top-left corner, and a
width and height, with all values in normalised coordinates (0.0 - 1.0). So, to
set a ROI at halfway across and down the sensor, and a width and height of a
quarter of the sensor, use:
.IP
.EX
-roi 0.5,0.5,0.25,0.25
.EE
.
.TP
.BR \-rot ", " \-\-rotation " \fIvalue\fR"
Sets the rotation of the image in the viewfinder and resulting image. This can
take any value from 0 upwards, but due to hardware constraints only 0, 90, 180,
and 270 degree rotations are supported.
.
.TP
.BR \-sa ", " \-\-saturation " \fIvalue\fR"
Sets the color saturation of the image, from -100 to 100. 0 is the default.
.
.TP
.BR \-set ", " \-\-settings
Retrieves the current camera settings and writes them to stdout.
.
.TP
.BR \-sh ", " \-\-sharpness " \fIvalue\fR"
Sets the sharpness of the image, from -100 to 100. 0 is the default.
.
.TP
.BR \-ss ", " \-\-shutter " \fIvalue\fR"
Sets the shutter open time to the specified value (in microseconds). Shutter
speed limits are as follows:
.TS
tab(|);
l l .
Camera Model|Max (microseconds)
\_|\_
.T&
l n .
Version 1.x (OV5647)|6000000\& (6s)
Version 2.x (IMX219)|10000000\& (10s)
HQ (IMX477)|200000000\& (200s)
.TE
.IP
Using values above these maximums will result in undefined behaviour.
.
.TP
.BR \-st ", " \-\-stats
Force recomputation of statistics on stills capture pass. Digital gain and AWB
are recomputed based on the actual capture frame statistics, rather than the
preceding preview frame.
.
.TP
.BR \-vf ", " \-\-vflip
Flips the preview and saved image horizontally.
.
.TP
.BR \-vs ", " \-\-vstab
In video mode only, turns on video stabilisation.
.
.
.SH STEREOSCOPIC (3D) OPTIONS
.
.TP
.BR \-3dswap ", " \-\-3dswap
Swaps the camera order used in stereoscopic imaging;
.B NOTE:
currently not working.
.
.TP
.BR \-dec ", " \-\-decimate
Halves the width and height of the stereo image.
.
.TP
.BR \-3d ", " \-\-stereo " \fImode\fR"
Select the specified stereo imaging mode;
.I sbs
selects side-by-side mode,
.I tb
selects top/bottom mode;
.I off
turns off stereo mode (the default).
.
.
.SH SEE ALSO
.BR raspistill (1),
.BR raspiyuv (1),
.BR raspivid (1),
.BR raspividyuv (1),
.BR vcgencmd (1),
.B [SOURCE]
.
.
.SH REFERENCES
.TP
.B [SOURCE]
https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md

461
host_applications/linux/apps/raspicam/raspistill.1 Normal file
View File

@@ -0,0 +1,461 @@
.TH RASPISTILL 1
.
.SH NAME
raspistill \- takes still JPEG captures with the Pi Camera Module
.
.
.SH SYNOPSIS
.SY raspistill
.OP \-3d mode
.OP \-3dswap
.OP \-a flags|text
.OP \-ae size,fg,bg
.OP \-ag value
.OP \-awb mode
.OP \-awbg b,r
.OP \-bm
.OP \-br value
.OP \-cfx u:v
.OP \-co value
.OP \-cs camera
.OP \-d ms
.OP \-dec
.OP \-dg value
.OP \-dn screen
.OP \-drc value
.OP \-dt
.OP \-e format
.OP \-ev value
.OP \-ex mode
.OP \-f
.OP \-fli mode
.OP \-fp
.OP \-fs num
.OP \-g
.OP \-gc
.OP \-gps
.OP \-gs scene
.OP \-gw x,y,w,h
.OP \-h size
.OP \-hf
.OP \-ifx effect
.OP \-ISO value
.OP \-k
.OP \-l filename
.OP \-md mode
.OP \-mm mode
.OP \-n
.OP \-o filename
.OP \-op opacity
.OP \-p x,y,w,h
.OP \-q quality
.OP \-r
.OP \-roi x,y,w,h
.OP \-rot value
.OP \-rs num
.OP \-s
.OP \-sa value
.OP \-set
.OP \-sh value
.OP \-ss value
.OP \-st
.OP \-t ms
.OP \-th x:y:q
.OP \-tl ms
.OP \-ts
.OP \-v
.OP \-vf
.OP \-w size
.OP \-x key=value
.YS
.
.SY raspistill
.OP \-?
.SY raspistill
.OP \-\-help
.YS
.
.
.SH DESCRIPTION
.B raspistill
is a command line utility for capturing still images from the Raspberry Pi
Camera Module (any version). It has numerous options which can be used to
customize the capture process, the preview display, or to perform more complex
operations like time-lapse or triggered captures.
.
.
.SH OPTIONS
The options documented in the following sections are specific to the
.B raspistill
utility, or commonly used with it. For full details of the other options (which
are common to all the camera utilities), please refer to the
.BR raspicam (7)
manual page.
.
.
.SH GENERAL OPTIONS
.
.TP
.BR \-? ", " \-\-help
Display a concise description of all parameters
.
.TP
.BR \-bm ", " \-\-burst
Sets burst capture mode. This prevents the camera from returning to preview
mode in between captures, meaning that captures can be taken closer together.
.
.TP
.BR \-d ", " \-\-demo " [\fIms\fR]"
This options cycles through the range of camera options. No capture is taken,
and the demo will end at the end of the timeout period, irrespective of whether
all the options have been cycled. The time between cycles should be specified
as a millisecond value.
.
.TP
.BR \-e ", " \-\-encoding " \fIformat\fR"
Valid options are
.IR jpg " (default),"
.IR bmp ,
.IR gif ", and"
.IR png .
Note that only the JPEG format
.RI ( "-e jpg" )
is hardware accelerated. All other image types will take much longer to save.
Also note that the filename suffix is completely ignored when deciding the
encoding of a file.
.
.TP
.BR \-x ", " \-\-exif " \fIkey=value\fR"
Allows the insertion of specific EXIF tags into the JPEG image. You can have up
to 32 EXIF tag entries. This is useful for tasks like adding GPS metadata. For
example, to set the longitude:
.IP
.EX
--exif GPS.GPSLongitude=5/1,10/1,15/1
.EE
.IP
would set the longitude to 5 degs, 10 minutes, 15 seconds. See
.B [EXIF]
documentation for more details on the range of tags available; the supported
tags are as follows:
.RS
.TP
.B IFD0.
.TQ
.B IFD1.
ImageWidth, ImageLength, BitsPerSample, Compression, PhotometricInterpretation,
ImageDescription, Make, Model, StripOffsets, Orientation, SamplesPerPixel,
RowsPerString, StripByteCounts, XResolution, YResolution, PlanarConfiguration,
ResolutionUnit, TransferFunction, Software, DateTime, Artist, WhitePoint,
PrimaryChromaticities, JPEGInterchangeFormat, JPEGInterchangeFormatLength,
YCbCrCoefficients, YCbCrSubSampling, YCbCrPositioning, ReferenceBlackWhite,
Copyright
.TP
.B EXIF.
ExposureTime, FNumber, ExposureProgram, SpectralSensitivity, ISOSpeedRatings,
OECF, ExifVersion, DateTimeOriginal, DateTimeDigitized,
ComponentsConfiguration, CompressedBitsPerPixel, ShutterSpeedValue,
ApertureValue, BrightnessValue, ExposureBiasValue, MaxApertureValue,
SubjectDistance, MeteringMode, LightSource, Flash, FocalLength, SubjectArea,
MakerNote, UserComment, SubSecTime, SubSecTimeOriginal, SubSecTimeDigitized,
FlashpixVersion, ColorSpace, PixelXDimension, PixelYDimension,
RelatedSoundFile, FlashEnergy, SpatialFrequencyResponse, FocalPlaneXResolution,
FocalPlaneYResolution, FocalPlaneResolutionUnit, SubjectLocation,
ExposureIndex, SensingMethod, FileSource, SceneType, CFAPattern,
CustomRendered, ExposureMode, WhiteBalance, DigitalZoomRatio,
FocalLengthIn35mmFilm, SceneCaptureType, GainControl, Contrast, Saturation,
Sharpness, DeviceSettingDescription, SubjectDistanceRange, ImageUniqueID
.TP
.B GPS.
GPSVersionID, GPSLatitudeRef, GPSLatitude, GPSLongitudeRef, GPSLongitude,
GPSAltitudeRef, GPSAltitude, GPSTimeStamp, GPSSatellites, GPSStatus,
GPSMeasureMode, GPSDOP, GPSSpeedRef, GPSSpeed, GPSTrackRef, GPSTrack,
GPSImgDirectionRef, GPSImgDirection, GPSMapDatum, GPSDestLatitudeRef,
GPSDestLatitude, GPSDestLongitudeRef, GPSDestLongitude, GPSDestBearingRef,
GPSDestBearing, GPSDestDistanceRef, GPSDestDistance, GPSProcessingMethod,
GPSAreaInformation, GPSDateStamp, GPSDifferential
.TP
.B EINT.
InteroperabilityIndex, InteroperabilityVersion, RelatedImageFileFormat,
RelatedImageWidth, RelatedImageLength
.RE
.
.TP
.BR \-fp ", " \-\-fullpreview
This runs the preview using the full resolution capture mode. Maximum frames
per second in this mode is 15fps, and the preview will have the same field of
view as the capture. Captures should happen more quickly, as no mode change
should be required. This feature is currently under development.
.
.TP
.BR \-h ", " \-\-height " \fIsize\fR"
Set the image height to
.IR size .
.
.TP
.BR \-k ", " \-\-keypress
The camera is run for the requested time
.RI ( \-t ),
and a capture can be initiated throughout that time by pressing the Enter key.
Pressing X then Enter will exit the application before the timeout is reached.
If the timeout is set to 0, the camera will run indefinitely until the user
presses X then Enter. Using the verbose option
.RI ( \-v )
will display a prompt asking for user input, otherwise no prompt is displayed.
.
.TP
.BR \-l ", " \-\-latest " \fIfilename\fR"
Makes a file system link under this name to the latest frame.
.
.TP
.BR \-o ", " \-\-output " \fIfilename\fR"
Specifies the output filename. If not specified, no file is saved.
If the filename is \(lq\-\(rq, then all output is send to stdout.
.
.TP
.BR \-q ", " \-\-quality " \fIvalue\fR"
Sets the JPEG compression quality from 0 to 100. 100 is nearly uncompressed, 75
is a good all-round value.
.
.TP
.BR \-r ", " \-\-raw
This option inserts the raw Bayer data from the camera into the JPEG metadata.
.
.TP
.BR \-rs ", " \-\-restart " \fInum\fR"
Sets the JPEG restart marker interval to a specific value. Can be useful for
lossy transport streams because it allows a broken JPEG file to still be
partially displayed.
.
.TP
.BR \-s ", " \-\-signal
The camera is run for the requested time
.RI ( -t ),
and a capture can be initiated throughout that time by sending a USR1 signal to
the camera process. This can be done using the
.BR killall (1)
command. For example:
.IP
.EX
killall -USR1 raspistill
.EE
.
.TP
.BR \-th ", " \-\-thumb " \fIx:y:q\fR"
Allows specification of the thumbnail image inserted into the JPEG file. If not
specified, defaults are a size of 64x48 at quality 35.
.
If
.I \-\-thumb none
is specified, no thumbnail information will be placed in the file. This reduces
the file size slightly.
.
.TP
.BR \-t ", " \-\-timeout " \fIms\fR"
The program will run for the specified length of time, in milliseconds.
It then takes the capture and saves it if an output is specified. If a timeout
value is not specified, then it is set to 5 seconds
.RI ( "\-t 5000" ).
Note that low values (less than 500ms, although it can depend on other
settings) may not give enough time for the camera to start up and provide
enough frames for the automatic algorithms like AWB and AGC to provide accurate
results.
.
If set to 0, the preview will run indefinitely, until stopped with Ctrl-C. In
this case no capture is made.
.
.TP
.BR \-v ", " \-\-verbose
Outputs debugging/information messages during the program run.
.
.TP
.BR \-w ", " \-\-width " \fIsize\fR"
Set the image width to
.IR size .
.
.
.SH TIMELAPSE OPTIONS
.
.TP
.BR \-tl ", " \-\-timelapse " \fIms\fR"
The specific value is the time between shots in milliseconds. Note that you
should specify
.I %04d
at the point in the filename where you want a frame count number to appear. So,
for example, the code below will produce a capture every 2 seconds, over a
total period of 30s, named \(lqimage0001.jpg\(rq, \(lqimage0002.jpg\(rq and so
on, through to \(lqimage0015.jpg\(rq:
.IP
.EX
-t 30000 -tl 2000 -o image%04d.jpg
.EE
.IP
Note that the
.I %04d
indicates a 4-digit number, with leading zeroes added to make the required
number of digits. So, for example,
.I %08d
would result in an 8-digit number.
.
If a timelapse value of 0 is entered, the application will take pictures as
fast as possible. Note that there's an minimum enforced pause of 30ms between
captures to ensure that exposure calculations can be made.
.
.TP
.BR \-dt ", " \-\-datetime
Instead of a simple frame number, the timelapse
.RI ( \-tl )
filenames will use a date/time value of the format mmddHHMMSS, where mm is the
month, dd is the day of the month, HH is the hour, MM is the minute, and SS is
the second.
.
.TP
.BR \-fr ", " \-\-framestart " \fInum\fR"
Specifies the first frame number in the timelapse
.RI ( \-tl ).
Useful if you have already saved a number of frames, and want to start again at
the next frame.
.
.TP
.BR \-ts ", " \-\-timestamp
Instead of a simple frame number, the timelapse
.RI ( \-tl )
file names will use a single number which is the Unix timestamp, i.e. the
seconds since 1970.
.
.
.SH GL OPTIONS
.
.TP
.BR \-g ", " \-\-gl
Draw preview to texture instead of using video render component.
.
.TP
.BR \-gc ", " \-\-glcapture
Capture the GL frame-buffer instead of the camera image.
.
.TP
.BR \-gs ", " \-\-glscene " \fIscene\fR"
Select the GL scene which can be
.IR square ,
.IR teapot ,
.IR mirror ,
.IR yuv ,
.IR sobel ", or"
.IR vcsm_square .
.
.TP
.BR \-gw ", " \-\-glwin " \fIx,y,w,h\fR"
Specifies the GL window settings as an
.I x,y
location and a width and height.
.
.
.SH EXIT STATUS
.
.IP 0
Application ran successfully
.RB ( EX_OK )
.IP 64
Bad command line parameter
.RB ( EX_USAGE )
.IP 70
Software or camera error
.RB ( EX_SOFTWARE )
.IP 130
Application terminated by Ctrl-C
.
.
.SH EXAMPLES
.
By default, captures are done at the highest resolution supported by the
sensor. This can be changed using the
.I \-w
and
.I \-h
command line options.
.
.TP
.B raspistill \-t 2000 \-o image.jpg
Take a default capture after 2s (times are specified in milliseconds) on the
viewfinder, saving in image.jpg.
.
.TP
.B raspistill \-t 2000 \-o image.jpg \-w 640 \-h 480
Take a capture at a different resolution.
.
.TP
.B raspistill \-t 2000 \-o image.jpg \-q 5
Reduce the quality considerably to reduce file size.
.
.TP
.B raspistill \-t 2000 \-o image.jpg \-p 100,100,300,200
Force the preview to appear at coordinate 100,100, with width 300 pixels and
height 200 pixels.
.
.TP
.B raspistill \-t 2000 \-o image.jpg \-n
Disable the preview entirely.
.
.TP
.B raspistill \-t 2000 \-o image.png –e png
Save the image as a PNG file (lossless compression, but slower than JPEG). Note
that the filename suffix is ignored when choosing the image encoding.
.
.TP
.B raspistill \-t 2000 \-o image.jpg \-x IFD0.Artist=Boris \-x GPS.GPSAltitude=1235/10
Add some EXIF information to the JPEG. This sets the Artist tag name to Boris,
and the GPS altitude to 123.5m. Note that if setting GPS tags you should set as
a minimum GPSLatitude, GPSLatitudeRef, GPSLongitude, GPSLongitudeRef,
GPSAltitude, and GPSAltitudeRef.
.
.TP
.B raspistill \-t 2000 \-o image.jpg \-ifx emboss
Set an emboss image effect.
.
.TP
.B raspistill \-t 2000 \-o image.jpg \-cfx 128:128
Set the U and V channels of the YUV image to specific values (128:128 produces
a greyscale image).
.
.TP
.B raspistill \-t 2000
Run preview for 2s, with no saved image.
.
.TP
.B raspistill \-t 600000 \-tl 10000 \-o image_num_%03d_today.jpg \-l latest.jpg
Take a time-lapse picture, every 10 seconds for 10 minutes (10 minutes =
600000ms), naming the files \(lqimage_num_001_today.jpg\(rq,
\(lqimage_num_002_today.jpg\(rq and so on, with the latest picture also
available under the name \(lqlatest.jpg\(rq.
.
.TP
.B raspistill \-t 2000 \-o \-
Take a picture and send the image data to stdout.
.
.TP
.B raspistill \-t 2000 \-o \- > my_file.jpg
Take a picture and send the image data to a file.
.
.TP
.B raspistill \-t 0 \-k \-o my_pics%02d.jpg
Run the camera forever, taking a picture when Enter is pressed.
.
.
.SH SEE ALSO
.BR raspicam (7),
.BR raspivid (1),
.BR raspividyuv (1),
.BR raspiyuv (1),
.BR vcgencmd (1),
.B [SOURCE]
.
.
.SH REFERENCES
.TP
.B [EXIF]
https://en.wikipedia.org/wiki/Exif
.
.TP
.B [SOURCE]
https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md

482
host_applications/linux/apps/raspicam/raspivid.1 Normal file
View File

@@ -0,0 +1,482 @@
.TH RASPIVID 1
.
.SH NAME
raspivid \- records H264 video with the Pi Camera Module
.
.
.SH SYNOPSIS
.SY raspivid
.OP \-3d mode
.OP \-3dswap
.OP \-ISO value
.OP \-a flags|text
.OP \-ae size,fg,bg
.OP \-ag value
.OP \-awb mode
.OP \-awbg b,r
.OP \-b bps
.OP \-br value
.OP \-c
.OP \-cd name
.OP \-cfx u:v
.OP \-co value
.OP \-cs camera
.OP \-d ms
.OP \-dg value
.OP \-dn screen
.OP \-drc value
.OP \-e
.OP \-ev value
.OP \-ex mode
.OP \-f
.OP \-fl
.OP \-fli mode
.OP \-fps fps
.OP \-g frames
.OP \-gps
.OP \-h size
.OP \-hf
.OP \-i state
.OP \-if type
.OP \-ifx effect
.OP \-ih
.OP \-k
.OP \-l
.OP \-lev level
.OP \-md mode
.OP \-mm mode
.OP \-n
.OP \-o filename
.OP \-op opacity
.OP \-p x,y,w,h
.OP \-pf profile
.OP \-pts filename
.OP \-qp num
.OP \-r filename
.OP \-rf format
.OP \-roi x,y,w,h
.OP \-rot value
.OP \-s
.OP \-sa value
.OP \-set
.OP \-sg ms
.OP \-sh value
.OP \-sl num
.OP \-sn num
.OP \-sp
.OP \-ss value
.OP \-stm
.OP \-t ms
.OP \-td on,off
.OP \-v
.OP \-vf
.OP \-w size
.OP \-wr num
.OP \-x filename
.YS
.
.SY raspivid
.OP \-?
.SY raspivid
.OP \-\-help
.YS
.
.
.SH DESCRIPTION
.B raspivid
is a command line utility for recording video from the Raspberry Pi Camera
Module (any version). It has numerous options which can be used to customize
the recording, the preview display, or to perform more complex operations like
circular buffering and video streaming.
.
.
.SH OPTIONS
The options documented in the following sections are specific to the
.B raspivid
utility, or commonly used with it. For full details of the other options (which
are common to all the camera utilities), please refer to the
.BR raspicam (7)
manual page.
.
.
.SH GENERAL OPTIONS
.
.TP
.BR \-? ", " \-\-help
Display a concise description of all parameters
.
.TP
.BR \-b ", " \-\-bitrate " \fIbps\fR"
Use bits per second, so 10Mbits/s would be
.IR "\-b 10000000" .
For H264, 1080p30 a high quality bitrate would be 15Mbits/s or more.
Maximum bitrate is 25Mbits/s
.RI ( "\-b 25000000" ),
but much over 17Mbits/s won't show noticeable improvement at 1080p30.
.
.TP
.BR \-c ", " \-\-circular
Select circular buffer mode. All encoded data is stored in a circular buffer
until a trigger is activated, then the buffer is saved.
.
.TP
.BR \-cd ", " \-\-codec " \fIname\fR"
Specifies the encoder codec to use. Options are
.I H264
and
.IR MJPEG .
H264 can encode up to 1080p, whereas MJPEG can encode upto the sensor size, but
at decreased framerates due to the higher processing and storage requirements.
.
.TP
.BR \-d ", " \-\-demo " [\fIms\fR]"
This options cycles through the range of camera options. No recording is taken,
and the demo will end at the end of the timeout period, irrespective of whether
all the options have been cycled. The time between cycles should be specified
as a millisecond value.
.
.TP
.BR \-fl ", " \-\-flush
Forces a flush of output data buffers as soon as video data is written. This
bypasses any OS caching of written data, and can decrease latency.
.
.TP
.BR \-fps ", " \-\-framerate " \fIfps\fR"
Specifies the frames per second to record. At present, the minimum frame rate
allowed is 2fps, and the maximum is 30fps. This is likely to change in the
future.
.
.TP
.BR \-h ", " \-\-height " \fIsize\fR"
Set the video height to
.IR size .
.
.TP
.BR \-if ", " \-\-irefresh " \fItype\fR"
Sets the H264 intra-refresh type. Possible types are:
.RS
.IP \(bu 2
.I cyclic
.IP \(bu
.I adaptive
.IP \(bu
.I both
.IP \(bu
.I cyclicrows
.RE
.
.TP
.BR \-i ", " \-\-initial " \fIstate\fR"
Define whether the camera will start paused or will immediately start
recording. Valid states are
.I record
or
.IR pause .
Note that if you are using a simple timeout (without
.I \-\-timed
or
.I \-\-keypress
or other options to activate recording), and
.I \-\-initial
is set to
.IR pause ,
no output will be recorded.
.
.TP
.BR \-ih ", " \-\-inline
Forces the stream to include PPS and SPS headers on every I-frame. Needed for
certain streaming cases e.g. Apple HLS. These headers are small, so don't
greatly increase the file size.
.
.TP
.BR \-g ", " \-\-intra " \fIframes\fR"
Sets the intra refresh period (GoP) rate for the recorded video. H264 video
uses a complete frame (I-frame) every intra refresh period, from which
subsequent frames are based. This option specifies the number of frames between
each I-frame. Larger numbers here will reduce the size of the resulting video,
and smaller numbers make the stream less error-prone.
.
.TP
.BR \-k ", " \-\-keypress
On each press of the Enter key, the recording will be paused or restarted.
Pressing X then Enter will stop recording and close the application. Note that
the timeout value
.RI ( \-t )
will be used to signal the end of recording, but is only checked after each
Enter keypress; so if the system is waiting for a keypress, even if the timeout
has expired, it will still wait for the keypress before exiting.
.
.TP
.BR \-lev ", " \-\-level " \fIlevel\fR"
Specifies the H264 encoder level to use for encoding. Options are
.IR 4 ,
.IR 4.1 ,
and
.IR 4.2 .
.
.TP
.BR \-l ", " \-\-listen
When using a network connection as the
.IR \-\-output ,
this option will make the sytem wait for a connection from the remote system
before sending data.
.
.TP
.BR \-o ", " \-\-output " \fIfilename\fR"
Specify the output filename. If not specified, no file is saved. If the
filename is \(lq\-\(rq, then all output is sent to stdout.
.
To connect to a remote IPv4 host, use
.I tcp
or
.I udp
followed by the required IP Address. e.g.
.I tcp://192.168.1.2:1234
or
.IR udp://192.168.1.2:1234 .
.IP
To listen on a TCP port (IPv4) and wait for an incoming connection use the
.I \-\-listen
option, e.g.
.I raspivid \-l \-o tcp://0.0.0.0:3333
will bind to all network interfaces,
.I raspivid \-l \-o tcp://192.168.1.1:3333
will bind to a local IPv4.
.
.TP
.BR \-e ", " \-\-penc
Switch on this option to display the preview after compression. This will show
any compression artefacts in the preview window. In normal operation, the
preview will show the camera output prior to being compressed. This option is
not guaranteed to work in future releases.
.
.TP
.BR \-pf ", " \-\-profile " \fIprofile\fR"
Sets the H264 profile to be used for the encoding. Options are:
.RS
.IP \(bu 2
.I baseline
.IP \(bu
.I main
.IP \(bu
.I high
.RE
.
.TP
.BR \-qp ", " \-\-qp " \fInum\fR"
Sets the initial quantisation parameter for the stream. Varies from
approximately 10 to 40, and will greatly affect the quality of the recording.
Higher values reduce quality and decrease file size. Combine this setting with
a bitrate of 0 to set a completely variable bitrate.
.
.TP
.BR \-r ", " \-\-raw " \fIfilename\fR"
Specify the output file name for any raw data files requested.
.
.TP
.BR \-rf " ," \-\-raw\-format " \fIformat\fR"
Specify the raw format to be used if raw output is requested. Valid formats are
.IR yuv ,
.IR rgb ,
and
.IR grey .
.I grey
simply saves the Y channel of the YUV image.
.
.TP
.BR \-pts ", " \-\-save-pts " \fIfilename\fR"
Saves timestamp information to the specified file. Useful as an input file to
.BR mkvmerge (1).
.
.TP
.BR \-sg ", " \-\-segment " \fIms\fR"
Rather than creating a single file, the file is split into segments of
approximately the number of milliseconds specified. In order to provide
different filenames, you should add
.I %04d
or similar at the point in the filename where you want a segment count number
to appear e.g:
.IP
.EX
\-\-segment 3000 \-o video%04d.h264
.EE
.IP
will produce video clips of approximately 3000ms (3s) long, named
\(lqvideo0001.h264\(rq, \(lqvideo0002.h264\(rq etc. The clips should be
seamless (no frame drops between clips), but the accuracy of each clip length
will depend on the intraframe period, as the segments will always start on an
I-frame. They will therefore always be equal or longer to the specified period.
.IP
The most recent version of
.B raspivid
will also allow the file name to be time-based, rather than using a segment
number. For example:
.IP
.EX
\-\-segment 3000 \-o video_%c.h264
.EE
.IP
will produce file names formatted like so:
\(lqvideo_Fri Jul 20 16:23:48 2018.h264\(rq
.IP
There are many different formatting options available - see
.BR strftime (3)
for a full list. Note than the
.I %d
and
.I %u
options are not available, as they are used for the segment number formatting,
and that some combinations may produce invalid file names.
.
.TP
.BR \-s ", " \-\-signal
Sending a
.I USR1
signal to the
.B raspivid
process will toggle between recording and paused. This can be done using the
.BR killall (1)
command, as below:
.IP
.EX
killall -USR1 raspivid
.EE
.IP
Note that the timeout value will be used to indicate the end of recording, but
is only checked after each receipt of the
.I USR1
signal; so if the system is waiting for a signal, even if the timeout has
expired, it will still wait for the signal before exiting.
.
.TP
.BR \-sl ", " \-\-slices " \fInum\fR"
Sets the number of horizontal slices per frame. The default is 1 (no slices).
.
.TP
.BR \-sp ", " \-\-split
When in
.I \-\-signal
or
.I \-\-keypress
mode, each time recording is restarted, a new file is created.
.
.TP
.BR \-stm ", " \-\-spstimings
Insert timing information into the SPS block.
.
.TP
.BR \-sn ", " \-\-start " \fInum\fR"
When outputting segments (with
.IR \-\-segment ),
this is the initial segment number, giving the ability to resume a previous
recording from a given segment. The default value is 1.
.
.TP
.BR \-td ", " \-\-timed " \fIon,off\fR"
This options allows the video capture to be paused and restarted at particular
time intervals. Two values are required: the on time and the off time, both
measured in milliseconds. On time is the amount of time the video is captured,
and off time is the amount it is paused. The total runtime of the application
is defined by the timeout option
.RI ( \-t ).
Note that the runtime may go slightly over the timeout setting depending on the
on and off times.
.IP
For example:
.IP
.EX
raspivid \-o test.h264 \-t 25000 \-\-timed 2500,5000
.EE
.IP
This will alternate between recording for 2500ms (2.5s), then pausing for
5000ms (5s) gaps, until 25000ms (25s) have elapsed. The resulting recording
will only be 10s long, since 4 segments of 2.5s = 10s, separated by 3 gaps of
5s = 15s, for a total of 25s:
.IP
.EX
Seconds 1 2
1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
RRRRR..........RRRRR..........RRRRR..........RRRRR
.EE
.
.TP
.BR \-t ", " \-\-timeout " \fIms\fR"
The total length of time that the program will run for. If not specified, the
default is 5000ms (5 seconds). If set to 0, the application will run
indefinitely until stopped with Ctrl-C.
.
.TP
.BR \-x ", " \-\-vectors " \fIfilename\fR"
Turns on output of motion vectors from the H264 encoder to the specified file
name.
.
.TP
.BR \-v ", " \-\-verbose
Outputs debugging/information messages during the program run.
.
.TP
.BR \-wr ", " \-\-wrap " \fInum\fR"
When outputting segments, this is the maximum the segment number can reach
before it's reset to 1, giving the ability to keep recording segments, but
overwriting the oldest one. So if set to 4, in the
.I \-\-segment
example above, the files produced will be \(lqvideo0001.h264\(rq,
\(lqvideo0002.h264\(rq, \(lqvideo0003.h264\(rq, and \(lqvideo0004.h264\(rq.
Once \(lqvideo0004.h264\(rq is recorded, the count will reset to 1, and
\(lqvideo0001.h264\(rq will be overwritten.
.
.
.SH EXIT STATUS
.
.IP 0
Application ran successfully
.RB ( EX_OK )
.IP 64
Bad command line parameter
.RB ( EX_USAGE )
.IP 70
Software or camera error
.RB ( EX_SOFTWARE )
.IP 130
Application terminated by Ctrl-C
.
.
.SH EXAMPLES
.
Image size and preview settings are the same as for still captures. The default
size for video recording is 1080p (1920x1080).
.
.TP
.B raspivid \-t 5000 \-o video.h264
Record a 5s clip with default settings (1080p30).
.
.TP
.B raspivid \-t 5000 \-o video.h264 \-b 3500000
Record a 5s clip at a specified bitrate (3.5Mbits/s).
.
.TP
.B raspivid \-t 5000 \-o video.h264 \-f 5
Record a 5s clip at a specified framerate (5fps).
.
.TP
.B raspivid \-t 5000 \-o \-
Encode a 5s camera stream and send the image data to stdout.
.
.TP
.B raspivid \-t 5000 \-o \- > my_file.h264
Encode a 5s camera stream and send the image data to a file.
.
.
.SH SEE ALSO
.BR raspicam (7),
.BR raspistill (1),
.BR raspividyuv (1),
.BR raspiyuv (1),
.BR vcgencmd (1),
.B [SOURCE]
.
.
.SH REFERENCES
.TP
.B [SOURCE]
https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md

276
host_applications/linux/apps/raspicam/raspividyuv.1 Normal file
View File

@@ -0,0 +1,276 @@
.TH RASPIVIDYUV 1
.
.SH NAME
raspividyuv \- records unencoded video with the Pi Camera Module
.
.
.SH SYNOPSIS
.SY raspividyuv
.OP \-3d mode
.OP \-3dswap
.OP \-ISO value
.OP \-a flags|text
.OP \-ae size,fg,bg
.OP \-ag value
.OP \-awb mode
.OP \-awbg b,r
.OP \-br value
.OP \-cfx u:v
.OP \-co value
.OP \-cs camera
.OP \-d ms
.OP \-dg value
.OP \-dn screen
.OP \-drc value
.OP \-ev value
.OP \-ex mode
.OP \-f
.OP \-fli mode
.OP \-fps fps
.OP \-gps
.OP \-h size
.OP \-hf
.OP \-i state
.OP \-ifx effect
.OP \-k
.OP \-l
.OP \-md mode
.OP \-mm mode
.OP \-n
.OP \-o filename
.OP \-op opacity
.OP \-p x,y,w,h
.OP \-pts filename
.OP \-roi x,y,w,h
.OP \-rot value
.OP \-s
.OP \-sa value
.OP \-set
.OP \-sh value
.OP \-ss value
.OP \-t ms
.OP \-td on,off
.OP \-v
.OP \-vf
.OP \-w size
.YS
.
.SY raspividyuv
.OP \-?
.SY raspividyuv
.OP \-\-help
.YS
.
.
.SH DESCRIPTION
.B raspividyuv
is a command line utility for recording unencoded video frames from the
Raspberry Pi Camera Module (any version), in YUV format by default (see
.BR [YUV] ).
It has numerous options which can be used to customize the recording, the
preview display, or to perform more complex operations like video streaming.
.
.
.SH OPTIONS
The options documented in the following sections are specific to the
.B raspividyuv
utility, or commonly used with it. For full details of the other options (which
are common to all the camera utilities), please refer to the
.BR raspicam (7)
manual page.
.
.
.SH GENERAL OPTIONS
.
.TP
.BR \-? ", " \-\-help
Display a concise description of all parameters
.
.TP
.BR \-d ", " \-\-demo " [\fIms\fR]"
This options cycles through the range of camera options. No recording is taken,
and the demo will end at the end of the timeout period, irrespective of whether
all the options have been cycled. The time between cycles should be specified
as a millisecond value.
.
.TP
.BR \-fps ", " \-\-framerate " \fIfps\fR"
Specifies the frames per second to record. At present, the minimum frame rate
allowed is 2fps, and the maximum is 30fps. This is likely to change in the
future.
.
.TP
.BR \-h ", " \-\-height " \fIsize\fR"
Set the video height to
.IR size .
.
.TP
.BR \-i ", " \-\-initial " \fIstate\fR"
Define whether the camera will start paused or will immediately start
recording. Valid states are
.I record
or
.IR pause .
Note that if you are using a simple timeout (without
.I \-\-timed
or
.I \-\-keypress
or other options to activate recording), and
.I \-\-initial
is set to
.IR pause ,
no output will be recorded.
.
.TP
.BR \-k ", " \-\-keypress
On each press of the Enter key, the recording will be paused or restarted.
Pressing X then Enter will stop recording and close the application. Note that
the timeout value
.RI ( \-t )
will be used to signal the end of recording, but is only checked after each
Enter keypress; so if the system is waiting for a keypress, even if the timeout
has expired, it will still wait for the keypress before exiting.
.
.TP
.BR \-l ", " \-\-listen
When using a network connection as the
.IR \-\-output ,
this option will make the sytem wait for a connection from the remote system
before sending data.
.
.TP
.BR \-y ", " \-\-luma
Only outputs the luma (Y) channel of the YUV image. This is effectively the
black and white, or intensity, part of the image. See
.B [YUV]
for more information.
.
.TP
.BR \-o ", " \-\-output " \fIfilename\fR"
Specify the output filename. If not specified, no file is saved. If the
filename is \(lq\-\(rq, then all output is sent to stdout.
.
To connect to a remote IPv4 host, use
.I tcp
or
.I udp
followed by the required IP Address. e.g.
.I tcp://192.168.1.2:1234
or
.IR udp://192.168.1.2:1234 .
.IP
To listen on a TCP port (IPv4) and wait for an incoming connection use the
.I \-\-listen
option, e.g.
.I raspividyuv \-l \-o tcp://0.0.0.0:3333
will bind to all network interfaces,
.I raspividyuv \-l \-o tcp://192.168.1.1:3333
will bind to a local IPv4.
.
.TP
.BR \-pts ", " \-\-save-pts " \fIfilename\fR"
Saves timestamp information to the specified file. Useful as an input file to
.BR mkvmerge (1).
.
.TP
.BR \-rgb ", " \-\-rgb
This option forces the video to be saved as RGB data with 8 bits per channel,
rather than YUV420.
.
Note that the video frames saved in
.B raspividyuv
are padded to a horizontal size divisible by 32, so there may be unused bytes
at the end of each line. Buffers are also padded vertically to be divisible by
16, and in the YUV mode, each plane of Y,U,V is padded in this way.
.
.TP
.BR \-s ", " \-\-signal
Sending a
.I USR1
signal to the
.B raspividyuv
process will toggle between recording and paused. This can be done using the
.BR killall (1)
command, as below:
.IP
.EX
killall -USR1 raspividyuv
.EE
.IP
Note that the timeout value will be used to indicate the end of recording, but
is only checked after each receipt of the
.I USR1
signal; so if the system is waiting for a signal, even if the timeout has
expired, it will still wait for the signal before exiting.
.
.TP
.BR \-td ", " \-\-timed " \fIon,off\fR"
This options allows the video capture to be paused and restarted at particular
time intervals. Two values are required: the on time and the off time, both
measured in milliseconds. On time is the amount of time the video is captured,
and off time is the amount it is paused. The total runtime of the application
is defined by the timeout option
.RI ( \-t ).
Note that the runtime may go slightly over the timeout setting depending on the
on and off times.
.IP
For example:
.IP
.EX
raspividyuv \-o test.h264 \-t 25000 \-\-timed 2500,5000
.EE
.IP
This will alternate between recording for 2500ms (2.5s), then pausing for
5000ms (5s) gaps, until 25000ms (25s) have elapsed. The resulting recording
will only be 10s long, since 4 segments of 2.5s = 10s, separated by 3 gaps of
5s = 15s, for a total of 25s:
.IP
.EX
Seconds 1 2
1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
RRRRR..........RRRRR..........RRRRR..........RRRRR
.EE
.
.TP
.BR \-t ", " \-\-timeout " \fIms\fR"
The total length of time that the program will run for. If not specified, the
default is 5000ms (5 seconds). If set to 0, the application will run
indefinitely until stopped with Ctrl-C.
.
.TP
.BR \-v ", " \-\-verbose
Outputs debugging/information messages during the program run.
.
.
.SH EXIT STATUS
.
.IP 0
Application ran successfully
.RB ( EX_OK )
.IP 64
Bad command line parameter
.RB ( EX_USAGE )
.IP 70
Software or camera error
.RB ( EX_SOFTWARE )
.IP 130
Application terminated by Ctrl-C
.
.
.SH SEE ALSO
.BR raspicam (7),
.BR raspistill (1),
.BR raspivid (1),
.BR raspiyuv (1),
.BR vcgencmd (1),
.B [SOURCE]
.
.
.SH REFERENCES
.TP
.B [SOURCE]
https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md
.
.TP
.B [YUV]
https://en.wikipedia.org/wiki/YUV

234
host_applications/linux/apps/raspicam/raspiyuv.1 Normal file
View File

@@ -0,0 +1,234 @@
.TH RASPIYUV 1
.
.SH NAME
raspiyuv \- takes unencoded still captures with the Pi Camera Module
.
.
.SH SYNOPSIS
.SY raspiyuv
.OP \-3d mode
.OP \-3dswap
.OP \-a flags|text
.OP \-ae size,fg,bg
.OP \-ag value
.OP \-awb mode
.OP \-awbg b,r
.OP \-bm
.OP \-br value
.OP \-cfx u:v
.OP \-co value
.OP \-cs camera
.OP \-dec
.OP \-dg value
.OP \-dn screen
.OP \-drc value
.OP \-ev value
.OP \-ex mode
.OP \-f
.OP \-fli mode
.OP \-fp
.OP \-gps
.OP \-h size
.OP \-hf
.OP \-ifx effect
.OP \-ISO value
.OP \-k
.OP \-l filename
.OP \-md mode
.OP \-mm mode
.OP \-n
.OP \-o filename
.OP \-op opacity
.OP \-p x,y,w,h
.OP \-roi x,y,w,h
.OP \-rot value
.OP \-s
.OP \-sa value
.OP \-set
.OP \-sh value
.OP \-ss value
.OP \-st
.OP \-t ms
.OP \-tl ms
.OP \-v
.OP \-vf
.OP \-w size
.YS
.
.SY raspiyuv
.OP \-?
.SY raspiyuv
.OP \-\-help
.YS
.
.
.SH DESCRIPTION
.B raspiyuv
is a command line utility for capturing unencoded still images from the
Raspberry Pi Camera Module (any version), in YUV format by default (see
.BR [YUV] ).
It has numerous options which can be used to customize the capture process, the
preview display, or to perform more complex operations like time-lapse or
triggered captures.
.
.
.SH OPTIONS
The options documented in the following sections are specific to the
.B raspiyuv
utility, or commonly used with it. For full details of the other options (which
are common to all the camera utilities), please refer to the
.BR raspicam (7)
manual page.
.
.
.SH GENERAL OPTIONS
.
.TP
.BR \-? ", " \-\-help
Display a concise description of all parameters
.
.TP
.BR \-bgr ", " \-\-bgr
Saves the image data as BGR data rather than YUV. See
.B \-\-rgb
below for more information.
.
.TP
.BR \-bm ", " \-\-burst
Sets burst capture mode. This prevents the camera from returning to preview
mode in between captures, meaning that captures can be taken closer together.
.
.TP
.BR \-fp ", " \-\-fullpreview
This runs the preview using the full resolution capture mode. Maximum frames
per second in this mode is 15fps, and the preview will have the same field of
view as the capture. Captures should happen more quickly, as no mode change
should be required. This feature is currently under development.
.
.TP
.BR \-h ", " \-\-height " \fIsize\fR"
Set the image height to
.IR size .
.
.TP
.BR \-k ", " \-\-keypress
The camera is run for the requested time
.RI ( \-t ),
and a capture can be initiated throughout that time by pressing the Enter key.
Pressing X then Enter will exit the application before the timeout is reached.
If the timeout is set to 0, the camera will run indefinitely until the user
presses X then Enter. Using the verbose option
.RI ( \-v )
will display a prompt asking for user input, otherwise no prompt is displayed.
.
.TP
.BR \-l ", " \-\-latest " \fIfilename\fR"
Makes a file system link under this name to the latest frame.
.
.TP
.BR \-y ", " \-\-luma
Only outputs the luma (Y) channel of the YUV image. This is effectively the
black and white, or intensity, part of the image. See
.B [YUV]
for more information.
.
.TP
.BR \-o ", " \-\-output " \fIfilename\fR"
Specifies the output filename. If not specified, no file is saved.
If the filename is \(lq\-\(rq, then all output is send to stdout.
.
.TP
.BR \-rgb ", " \-\-rgb
This option forces the image to be saved as RGB data with 8 bits per channel,
rather than YUV420.
.
Note that the image buffers saved in
.B raspiyuv
are padded to a horizontal size divisible by 32, so there may be unused bytes
at the end of each line. Buffers are also padded vertically to be divisible by
16, and in the YUV mode, each plane of Y,U,V is padded in this way.
.
.TP
.BR \-s ", " \-\-signal
The camera is run for the requested time
.RI ( -t ),
and a capture can be initiated throughout that time by sending a USR1 signal to
the camera process. This can be done using the
.BR killall (1)
command. For example:
.IP
.EX
killall -USR1 raspiyuv
.EE
.
.TP
.BR \-v ", " \-\-verbose
Outputs debugging/information messages during the program run.
.
.TP
.BR \-w ", " \-\-width " \fIsize\fR"
Set the image width to
.IR size .
.
.
.SH TIMELAPSE OPTIONS
.
.TP
.BR \-tl ", " \-\-timelapse " \fIms\fR"
The specific value is the time between shots in milliseconds. Note that you
should specify
.I %04d
at the point in the filename where you want a frame count number to appear. So,
for example, the code below will produce a capture every 2 seconds, over a
total period of 30s, named \(lqimage0001.jpg\(rq, \(lqimage0002.jpg\(rq and so
on, through to \(lqimage0015.jpg\(rq:
.IP
.EX
-t 30000 -tl 2000 -o image%04d.jpg
.EE
.IP
Note that the
.I %04d
indicates a 4-digit number, with leading zeroes added to make the required
number of digits. So, for example,
.I %08d
would result in an 8-digit number.
.
If a timelapse value of 0 is entered, the application will take pictures as
fast as possible. Note that there's an minimum enforced pause of 30ms between
captures to ensure that exposure calculations can be made.
.
.
.SH EXIT STATUS
.
.IP 0
Application ran successfully
.RB ( EX_OK )
.IP 64
Bad command line parameter
.RB ( EX_USAGE )
.IP 70
Software or camera error
.RB ( EX_SOFTWARE )
.IP 130
Application terminated by Ctrl-C
.
.
.SH SEE ALSO
.BR raspicam (7),
.BR raspistill (1),
.BR raspivid (1),
.BR raspividyuv (1),
.BR vcgencmd (1),
.B [YUV],
.B [SOURCE]
.
.
.SH REFERENCES
.TP
.B [SOURCE]
https://www.raspberrypi.org/\:documentation/\:raspbian/\:applications/\:camera.md
.
.TP
.B [YUV]
https://en.wikipedia.org/wiki/YUV

1
host_applications/linux/apps/tvservice/CMakeLists.txt
View File

@@ -3,3 +3,4 @@ target_link_libraries(tvservice vchostif)
install(TARGETS tvservice
RUNTIME DESTINATION bin)
install(FILES tvservice.1 DESTINATION man/man1)

155
host_applications/linux/apps/tvservice/tvservice.1 Normal file
View File

@@ -0,0 +1,155 @@
.TH TVSERVICE 1
.
.SH NAME
tvservice \- get and set information from attached displays
.
.
.SH SYNOPSIS
.SY tvservice
.OP \-a
.OP \-c "mode aspect p"
.OP \-d filename
.OP \-e "group mode drive"
.OP \-j
.OP \-l
.OP \-m group
.OP \-M
.OP \-n
.OP \-o
.OP \-p
.OP \-s
.OP \-t
.OP \-v id
.YS
.
.SY tvservice
.B \-h
.SY tvservice
.B \-\-help
.YS
.
.
.SH DESCRIPTION
.B tvservice
is a command line application used to get and set information about the
display, targeted mainly at HDMI video and audio.
.
Typing
.B tvservice
by itself will display a list of available command line options.
.
.
.SH OPTIONS
.
.TP
.BR \-a ", " \-\-audio
Shows the current settings for the audio mode, including channels, sample rate
and sample size.
.
.TP
.BR \-c ", " \-\-sdtvon " \(dq\fImode aspect \fR[\fIP\fR]\(dq"
Power on the SDTV (composite output) with the specified
.IR mode ,
PAL or NSTC, and the specified
.IR aspect ,
4:3, 14:9, 16:9. The optional \(lqP\(rq parameter can be used to specify
progressive mode.
.
.TP
.BR \-d ", " \-\-dumpid " \fIfilename\fR"
Save the current EDID to the specified filename. You can then use
.BR edid-decode (1)
to display the data in a human readable form. See
.B [EDID]
for more information on the EDID contents.
.
.TP
.BR \-e ", " \-\-explicit " \(dq\fIgroup mode drive\fR\(dq"
Power on the HDMI display with the specified settings.
.
The
.I group
option can be one of CEA, DMT, CEA_3D_SBS, CEA_3D_TB, CEA_3D_FP, or CEA_3D_FS;
.I mode
is one of the modes returned from the
.B \-\-modes
option. Finally,
.I drive
can be HDMI or DVI.
.
.TP
.BR \-j ", " \-\-json
When used in combination with the
.B \-\-modes
option, displays the mode information in JSON format.
.
.TP
.BR \-l ", " \-\-list
Lists all attached displays and their display ID.
.
.TP
.BR \-m ", " \-\-modes " \fIgroup\fR"
Shows a list of display modes available in the specified
.IR group ,
which can be either CEA or DMT.
.
.TP
.BR \-M ", " \-\-monitor
Monitors for any HDMI events, for example unplugging or attaching.
.
.TP
.BR \-n ", " \-\-name
Extracts the display name from the EDID data and shows it.
.
.TP
.BR \-o ", " \-\-off
Powers off the display output.
.IP
.B Important Note:
Powering off the output using this command will also destroy any
framebuffers/dispmanx layers associated with the display. These are NOT
re-established with a subsequent power on, so will result in a blank screen.
.IP
A better option is to use the
.BR vcgencmd (1)
.B display_power
option, as this will retain any framebuffers, so when the power is turned back
on the display will be the returned to the previous power on state.
.
.TP
.BR \-p ", " \-\-preferred
Power on the HDMI output with preferred settings.
.
.TP
.BR \-s ", " \-\-status
Shows the current settings for the display mode, including mode, resolution,
and frequency.
.
.TP
.BR \-t ", " \-\-ntsc
Use 59.94Hz (NTSC frequency) rather than 60Hz for HDMI mode.
.
.TP
.BR \-v ", " \-\-device " \fIid\fR"
Specifies the ID of the device to use; see the output of
.B \-\-list
for available IDs.
.
.
.SH SEE ALSO
.BR vcgencmd (1),
.BR edid-decode (1)
.
.PP
Full documentation at
.BR [SOURCE] .
.
.
.SH REFERENCES
.TP
.B [EDID]
https://en.wikipedia.org/wiki/Extended_Display_Identification_Data
.
.TP
.B [SOURCE]
https://www.raspberrypi.org/documentation/raspbian/applications/tvservice.md

2
host_applications/linux/apps/vcmailbox/CMakeLists.txt
View File

@@ -3,3 +3,5 @@ target_link_libraries(vcmailbox vchostif)
install(TARGETS vcmailbox
RUNTIME DESTINATION bin)
install(FILES vcmailbox.1 DESTINATION man/man1)
install(FILES vcmailbox.7 raspiotp.7 raspirev.7 DESTINATION man/man7)

228
host_applications/linux/apps/vcmailbox/raspiotp.7 Normal file
View File

@@ -0,0 +1,228 @@
.TH RASPIOTP 7
.
.SH NAME
raspiotp \- the Raspberry Pi OTP register bits
.
.
.SH DESCRIPTION
.
All SoCs used by the Raspberry Pi range have a inbuilt One-Time Programmable
(OTP) memory block.
It is 66 32-bit values long, although only a few locations have
factory-programmed data.
The
.BR vcgencmd (1)
utility can be used to display the contents of the OTP like so:
.PP
.EX
$ \fBvcgencmd otp_dump\fR
.EE
.
.
.SH OTP REGISTERS
This list contains the publicly available information on the registers. If a
register or bit is not defined here, then it is not public.
.
.TP
.B 17
bootmode register
.RS
.TP
.B Bit 1
sets the oscillator frequency to 19.2MHz
.TP
.B Bit 3
enables pull ups on the SDIO pins
.TP
.B Bit 19
enables GPIO bootmode
.TP
.B Bit 20
sets the bank to check for GPIO bootmode
.TP
.B Bit 21
enables booting from SD card
.TP
.B Bit 22
sets the bank to boot from
.TP
.B Bit 28
enables USB device booting
.TP
.B Bit 29
enables USB host booting (ethernet and mass storage)
.RE
.
.TP
.B 18
copy of bootmode register
.
.TP
.B 28
serial number
.
.TP
.B 29
~(serial number)
.
.TP
.B 30
revision code;
.
.BR raspirev (7)
.TP
.B 36-43
customer OTP values (see
.B INDUSTRIAL USE
below)
.
.TP
.B 45
MPG2 decode key
.
.TP
.B 46
WVC1 decode key
.
.TP
.B 64-65
MAC address; if set, system will use this in preference to the automatically generated address based on the serial number
.
.TP
.B 66
advanced boot register
.RS
.TP
.B Bits 0-6
GPIO for ETH_CLK output pin
.TP
.B Bit 7
enables ETH_CLK output
.TP
.B Bits 8-14
GPIO for LAN_RUN output pin
.TP
.B Bit 15
enables LAN_RUN output
.TP
.B Bit 24
extends USB HUB timeout parameter
.TP
.B Bit 25
ETH_CLK frequency: 0=25MHz, 1=24MHz
.RE
.
.
.SH INDUSTRIAL USE
The Raspberry Pi is often used as part of another product. This section
describes some extra facilities available to use other capabilities of the Pi.
.
.SS Customer OTP settings
There are a number of OTP values that can be used. To see a list of all the OTP
values, you can use:
.PP
.EX
$ \fBvcgencmd otp_dump\fR
.EE
.PP
In register locations 36 to 43 (inclusive), there are eight rows of 32 bits
available for the customer (detailed in
.B OTP REGISTERS
above).
.PP
To program these bits, you will need to use the vcmailbox. This is a Linux
driver interface to the firmware which will handle the programming of the rows.
To do this, please refer to the documentation at [MAILBOX], and the
.BR vcmailbox (1)
example application. For example:
.PP
.EX
$ \fBvcmailbox 0x00010004 8 8 0 0\fR
0x00000020 0x80000000 0x00010004 0x00000008 0x800000008 0xnnnnnnnn
0x00000000 0x00000000
.EE
.PP
The above uses the
.B GET_BOARD_SERIAL
tag (detailed under [MAILBOX]) with a request size of 8 bytes and response
size of 8 bytes (sending two integers for the request 0, 0). The response to
this will be two integers (0x00000020 and 0x80000000) followed by the tag code,
the request length, the response length (with the 31st bit set to indicate that
it is a response) then the 64 bit serial number (where the MS 32bits are always
0).
.PP
To set the customer OTP values you will need to use the
.B SET_CUSTOMER_OTP
(0x38021) tag as follows:
.PP
.EX
$ \fBvcmailbox 0x00038021 \fI[8+rows*4] [8+rows*4] [start] [rows] [value]\fR ...
.EE
.TP
.B start
the first row to program from 0-7
.TP
.B rows
number of rows to program
.TP
.B value
each value to program
.PP
So, to program OTP customer rows 4, 5, and 6 to 0x11111111, 0x22222222,
0x33333333 respectively, you would use:
.PP
.EX
$ \fBvcmailbox 0x00038021 20 20 4 3 0x11111111 0x22222222 0x33333333\fR
.EE
.PP
This will then program rows 40, 41, and 42. To read the values back, you can
use:
.PP
.EX
$ \fBvcmailbox 0x00030021 20 20 4 3 0 0 0\fR
0x0000002c 0x80000000 0x00030021 0x00000014 0x80000014 0x00000000
0x00000003 0x11111111 0x22222222 0x33333333
.EE
.PP
If you'd like to integrate this functionality into your own code, you should be
able to achieve this by using the vcmailbox.c code as an example.
.
.SS Locking the OTP changes
It is possible to lock the OTP changes to avoid them being edited again. This
can be done using a special argument with the OTP write mailbox:
.PP
.EX
$ \fBvcmailbox 0x00038021 8 8 0xffffffff 0xaffe0000\fR
.EE
.PP
Once locked, the customer OTP values can no longer be altered. Note that this
locking operation is irreversible.
.
.SS Making customer OTP bits unreadable
It is possible to prevent the customer OTP bits from being read at all. This
can be done using a special argument with the OTP write mailbox:
.PP
.EX
$ \fBvcmailbox 0x00038021 8 8 0xffffffff 0xaffebabe\fR
.EE
.PP
This operation is unlikely to be useful for the vast majority of users, and is
irreversible.
.
.
.SH SEE ALSO
.BR vcgencmd (1),
.BR raspirev (7),
.B [SOURCE]
.
.
.SH REFERENCES
.TP
.B [MAILBOX]
https://github.com/raspberrypi/firmware/wiki/Mailbox-property-interface
.
.TP
.B [SOURCE]
https://www.raspberrypi.org/documentation/hardware/raspberrypi/otpbits.md
and
https://www.raspberrypi.org/documentation/hardware/industrial/README.md

332
host_applications/linux/apps/vcmailbox/raspirev.7 Normal file
View File

@@ -0,0 +1,332 @@
.TH RASPIREV 7
.
.SH NAME
raspirev \- Raspberry Pi revision codes
.
.
.SH DESCRIPTION
Each distinct Raspberry Pi model revision has a unique revision code. You can
look up a Raspberry Pi's revision code by running:
.PP
.EX
$ \fBcat /proc/cpuinfo\fR
.EE
.PP
The last three lines show the hardware type, the revision code, and the Pi's
unique serial number. For example:
.PP
.EX
Hardware : BCM2835
Revision : a02082
Serial : 00000000765fc593
.EE
.PP
.B Note:
As of the 4.9 kernel, all Pis report BCM2835, even those with BCM2836, BCM2837
and BCM2711 processors. You should not use this string to detect the processor.
Decode the revision code using the information below, or read
.I /sys/firmware/devicetree/base/model
.
.
.SH OLD-STYLE REVISION CODES
The first set of Raspberry Pi models were given sequential hex revision codes
from 0002 to 0015:
.TS
tab(|);
l l l l l .
Code|Model|Revision|RAM|Manufacturer
\_|\_|\_|\_|\_
0002|B|1.0|256MB|Egoman
0003|B|1.0|256MB|Egoman
0004|B|2.0|256MB|Sony UK
0005|B|2.0|256MB|Qisda
0006|B|2.0|256MB|Egoman
0007|A|2.0|256MB|Egoman
0008|A|2.0|256MB|Sony UK
0009|A|2.0|256MB|Qisda
000d|B|2.0|512MB|Egoman
000e|B|2.0|512MB|Sony UK
000f|B|2.0|512MB|Egoman
0010|B+|1.2|512MB|Sony UK
0011|CM1|1.0|512MB|Sony UK
0012|A+|1.1|256MB|Sony UK
0013|B+|1.2|512MB|Embest
0014|CM1|1.0|512MB|Embest
0015|A+|1.1|256MB/512MB|Embest
.TE
.
.
.SH NEW-STYLE REVISION CODES
With the launch of the Raspberry Pi 2, new-style revision codes were
introduced. Rather than being sequential, each bit of the hex code represents a
piece of information about the revision:
.PP
.EX
NOQuuuWuFMMMCCCCPPPPTTTTTTTTRRRR
.EE
.
.TP
.B N
Overvoltage
.PD 0
.RS
.TP
.B 0
Overvoltage allowed
.TP
.B 1
Overvoltage disallowed
.RE
.PD
.
.TP
.B O
OTP Programming; see
.BR raspiotp (7)
.PD 0
.RS
.TP
.B 0
OTP programming allowed
.TP
.B 1
OTP programming disallowed
.RE
.PD
.
.TP
.B Q
OTP Reading; see
.BR raspiotp (7)
.PD 0
.RS
.TP
.B 0
OTP reading allowed
.TP
.B 1
OTP reading disallowed
.RE
.PD
.
.TP
.BR uuu
Unused
.
.TP
.B W
Warranty bit
.PD 0
.RS
.TP
.B 0
Warranty is intact
.TP
.B 1
Warranty has been voided by overclocking
.RE
.PD
.
.TP
.B u
Unused
.
.TP
.B F
New flag
.PD 0
.RS
.TP
.B 1
new-style revision
.TP
.B 0
old-style revision
.RE
.PD
.
.TP
.B MMM
Memory size
.PD 0
.RS
.TP
.B 0
256MB
.TP
.B 1
512MB
.TP
.B 2
1GB
.TP
.B 3
2GB
.TP
.B 4
4GB
.TP
.B 5
8GB
.RE
.PD
.
.TP
.B CCCC
Manufacturer
.PD 0
.RS
.TP
.B 0
Sony UK
.TP
.B 1
Egoman
.TP
.B 2
Embest
.TP
.B 3
Sony Japan
.TP
.B 4
Embest
.TP
.B 5
Stadium
.RE
.PD
.
.TP
.B PPPP
Processor
.PD 0
.RS
.TP
.B 0
BCM2835
.TP
.B 1
BCM2836
.TP
.B 2
BCM2837
.TP
.B 3
BCM2711
.RE
.PD
.
.TP
.B TTTTTTTT
Type
.PD 0
.RS
.TP
.B 0
A
.TP
.B 1
B
.TP
.B 2
A+
.TP
.B 3
B+
.TP
.B 4
2B
.TP
.B 5
Alpha (early prototype)
.TP
.B 6
CM1
.TP
.B 8
3B
.TP
.B 9
Zero
.TP
.B a
CM3
.TP
.B c
Zero W
.TP
.B d
3B+
.TP
.B e
3A+
.TP
.B f
Internal use only
.TP
.B 10
CM3+
.TP
.B 11
4B
.TP
.B 13
400
.TP
.B 14
CM4
.RE
.PD
.
.TP
.B RRRR
Revision (0, 1, 2, etc.)
.PP
New-style revision codes in use at the time of writing:
.TS
tab(|);
l l l l l .
Code|Model|Revision|RAM|Manufacturer
\_|\_|\_|\_|\_
900021|A+|1.1|512MB|Sony UK
900032|B+|1.2|512MB|Sony UK
900092|Zero|1.2|512MB|Sony UK
900093|Zero|1.3|512MB|Sony UK
9000c1|Zero W|1.1|512MB|Sony UK
9020e0|3A+|1.0|512MB|Sony UK
920092|Zero|1.2|512MB|Embest
920093|Zero|1.3|512MB|Embest
900061|CM|1.1|512MB|Sony UK
a01040|2B|1.0|1GB|Sony UK
a01041|2B|1.1|1GB|Sony UK
a02082|3B|1.2|1GB|Sony UK
a020a0|CM3|1.0|1GB|Sony UK
a020d3|3B+|1.3|1GB|Sony UK
a02042|2B (BCM2837)|1.2|1GB|Sony UK
a21041|2B|1.1|1GB|Embest
a22042|2B (BCM2837)|1.2|1GB|Embest
a22082|3B|1.2|1GB|Embest
a220a0|CM3|1.0|1GB|Embest
a32082|3B|1.2|1GB|Sony Japan
a52082|3B|1.2|1GB|Stadium
a22083|3B|1.3|1GB|Embest
a02100|CM3+|1.0|1GB|Sony UK
a03111|4B|1.1|1GB|Sony UK
b03111|4B|1.1|2GB|Sony UK
b03112|4B|1.2|2GB|Sony UK
c03111|4B|1.1|4GB|Sony UK
c03112|4B|1.2|4GB|Sony UK
d03114|4B|1.4|8GB|Sony UK
.TE
.
.
.SH SEE ALSO
.BR raspiotp (7),
.B [SOURCE]
.
.
.SH REFERENCES
.TP
.B [SOURCE]
https://www.raspberrypi.org/documentation/hardware/raspberrypi/revision-codes/README.md

35
host_applications/linux/apps/vcmailbox/vcmailbox.1 Normal file
View File

@@ -0,0 +1,35 @@
.TH VCMAILBOX 1
.
.SH NAME
vcmailbox \- send messages to the VideoCore via the mailbox
.
.
.SH SYNOPSIS
.SY vcmailbox
.RI [ word0 ]
.RI [ word1 ]
\|.\|.\|.
.
.
.SH DESCRIPTION
.B vcmailbox
is a low-level utility for sending mailbox messages to the VideoCore. See
.B [MAILBOX]
or
.BR vcmailbox (7)
for more information on the available messages and their respective formats.
and
.BR raspiotp (7)
for some examples of typical usage.
.
.
.SH SEE ALSO
.BR vcgencmd (1),
.BR raspiotp (7),
.B [MAILBOX]
.
.
.SH REFERENCES
.TP
.B [MAILBOX]
https://github.com/raspberrypi/firmware/wiki/Mailbox-property-interface

2237
host_applications/linux/apps/vcmailbox/vcmailbox.7 Normal file
View File

File diff suppressed because it is too large Load Diff