Useful Unix Commands

Networking

SSH

SSH (Secure Shell) is used to securely connect from a local to a remote system (ex. from a laptop to a coprocessor). Unlike other commands on this page, ssh is not Unix specific and can be done on Windows and MacOS from their respective terminals.

Note

You may see a warning similar to The authenticity of host 'xxx' can't be established... or WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!, in most cases this can be safely ignored if you have confirmed that you are connecting to the correct host over a secure connection, and the fingerprint will change when your operating system is reinstalled or PhotonVision’s coprocessor image is re-flashed. This can also occur if you have multiple coprocessors with the same hostname on your network. You can read more about it here

Example:

ssh photon@hostname

For PhotonVision images, the username will be photon and the password will be vision.

ip

Run ip address with your coprocessor connected to a monitor in order to see its IP address and other network configuration information.

Your output might look something like this:

2: end1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
    link/ether de:9a:8f:7d:31:aa brd ff:ff:ff:ff:ff:ff
    inet 10.88.47.12/24 brd 10.88.47.255 scope global dynamic noprefixroute end1
        valid_lft 27367sec preferred_lft 27367sec

In this example, the numbers following inet (10.88.47.12) are your IP address.

ping

ping is a command-line utility used to test the reachability of a host on an IP network. It also measures the round-trip time for messages sent from the originating host to a destination computer. It can be used to determine if a network interface is available, which can be helpful when debugging.

File Transfer

All files under /opt/photonvision are owned by the root user. This means that if you want to modify them, the commands to do so must be ran as sudo.

SCP

SCP (Secure Copy) is used to securely transfer files between local and remote systems.

Example:

scp [file] pi@hostname:/path/to/destination

SFTP

SFTP (SSH File Transfer Protocol) is another option for transferring files between local and remote systems.

Filezilla

Filezilla is a GUI alternative to SCP and SFTP. It is available for Windows, MacOS, and Linux.

Miscellaneous

v4l2-ctl

v4l2-ctl is a command-line tool for controlling video devices.

List available video devices (used to verify the device recognized a connected camera):

v4l2-ctl --list-devices

List supported formats and resolutions for a specific video device:

v4l2-ctl --list-formats-ext --device /path/to/video_device

List all video device’s controls and their values:

v4l2-ctl --list-ctrls --device path/to/video_device

Note

This command is especially useful in helping to debug when certain camera controls, like exposure, aren’t behaving as expected. If you see an error in the logs similar to WARNING 30: failed to set property [property name] (UsbCameraImpl.cpp:646), that means that PhotonVision is trying to use a control that doesn’t exist or has a different name on your hardware. If you encounter this issue, please file an issue with the necessary logs and output of the v4l2-ctl --list-ctrls command.

systemctl

systemctl is a command that controls the systemd system and service manager.

Start PhotonVision:

systemctl start photonvision

Stop PhotonVision:

systemctl stop photonvision

Restart PhotonVision:

systemctl restart photonvision

Check the status of PhotonVision:

systemctl status photonvision

journalctl

journalctl is a command that queries the systemd journal, which is a logging system used by many Linux distributions.

View the PhotonVision logs:

journalctl --output cat -u photonvision

View the PhotonVision logs in real-time:

journalctl --output cat -u photonvision -f

--output cat is used to prevent journalctl from printing its own timestamps, because we log our own timestamps.

lsusb

lsusb is a command that can be used to find all the USB buses on a device. When run with the --tree flag, it will give you more information on the available ports and connected devices. See the example below.

photon@photonvision:~$ lsusb -t
/:  Bus 001.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/4p, 480M
    |__ Port 001: Dev 002, If 0, Class=Video, Driver=uvcvideo, 480M
    |__ Port 001: Dev 002, If 1, Class=Video, Driver=uvcvideo, 480M
    |__ Port 001: Dev 002, If 2, Class=Audio, Driver=snd-usb-audio, 480M
    |__ Port 001: Dev 002, If 3, Class=Audio, Driver=snd-usb-audio, 480M
    |__ Port 002: Dev 003, If 0, Class=Video, Driver=uvcvideo, 480M
    |__ Port 002: Dev 003, If 1, Class=Video, Driver=uvcvideo, 480M
/:  Bus 002.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/4p, 5000M
    |__ Port 003: Dev 002, If 0, Class=Vendor Specific Class, Driver=ax_usb_nic, 5000M
/:  Bus 003.Port 001: Dev 001, Class=root_hub, Driver=xhci-hcd/1p, 480M

The most important information from this list is the bandwitdth. This is the last number we see, followed by an M (megabytes).

usbtop

usbtop is a program that can be used to monitor traffic on your device’s USB buses. To use it, run sudo modprobe usbmon then sudo usbtop. An example output can be found below.

Bus ID 1 (Raw USB traffic, bus number 1)	To device	From device
  Device ID 1 :			                    0.00 kb/s	0.00 kb/s
  Device ID 2 :			                    141.71 kb/s	23595.81 kb/s
  Device ID 3 :			                    0.13 kb/s	0.13 kb/s
Bus ID 2 (Raw USB traffic, bus number 2)	To device	From device
  Device ID 1 :			                    0.00 kb/s	0.00 kb/s
  Device ID 2 :			                    450.42 kb/s	17.45 kb/s
Bus ID 3 (Raw USB traffic, bus number 3)	To device	From device
  Device ID 1 :			                    0.00 kb/s	0.00 kb/s

The above output can be used to debug USB bandwidth issues, by comparing the size of data being sent with the bandwidth limits (bandwidth limits can be found using lsusb).