Welcome to picast’s documentation!

A Simple Wireless Display Receiver on Raspberry Pi

Travis test status https://badge.fury.io/py/picast.svg Documentation status https://coveralls.io/repos/github/miurahr/picast/badge.svg?branch=master

Description

picast is a simple wifi display receiver written by Python3 on Raspberry Pi.

Dependency

picast depends several external utilities and some are only on Raspbian.

  • tvservice (raspbian only)
  • udhcpd (debian/ubuntu only)
  • wpa_supplicant
  • wpa_cli
  • vlc

Installation and run

Run apt install command on Raspbian(buster or later) / Raspberry Pi Zero W/WH, RaPi 3B+, RaPi 4.

$ sudo apt install net-tools python3 udhcpd python-gst-1.0 libgtk-3-dev python3-gi python3-pip gir1.2-gtk-3.0
$ sudo apt install gir1.2-gstreamer-1.0 gir1.2-gst-plugins-base-1.0
$ sudo apt install gstreamer1.0-plugins-good gstreamer1.0-gtk3 gstreamer1.0-plugins-rtp
$ sudo apt install gstreamer1.0-omx-rpi gstreamer1.0-omx-rpi-config vlc
$ sudo apt install --no-install-recommends lxde

$ python3 -m pip install picast
$ picast

Customize

When you want customize for your environment, please copy picast/settings.ini to your favorit place and edit it.

then launch picast such as follows:

$ picast --config /home/pi/settings.ini

Development

$ sudo apt install gstreamer1.0-tools
$ git clone https://github.com/miurahr/picast.git picast
$ cd picast
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install -U pip
$ pip install -r requirements.txt
$ picast --debug

Preparation

Increase GPU memory for decoding fullHD video stream. add gpu_mem=128 to /boot/config.txt

Usage

Picast search for the wireless display named “picast” on the source device you want to cast. Use “12345678” for a WPS PIN number. It is recommended to initiate the termination of the receiver on the source side. After Pi connects to the source, it has an IP address of 192.168.173.80.

These parameters are configured in settings.ini.

Autostart

Edit /home/pi/.config/lxsessions/LXDE/autostart

@xscreensaver -no-splash
@lxterminal -l -e /home/pi/picast/bin/picast

Debug

There is a debug log at /var/tmp/picast.log. It is configured in logging.ini.

Known issues

  • Latency: Limited by the implementation of the RTP player used.
  • WiFi: The on-board WiFi chip on Pi 3/Zero W only supports 2.4GHz. Due to the overcrowded nature of the 2.4GHz spectrum and the use of unreliable rtp transmission, you may experience some video glitching/audio stuttering. It may be better with Pi 3B+/4 that support IEEE802.11ac 5GHz.
  • HDCP(content protection): Neither the key nor the hardware is available on Pi and therefore is not supported.

Design

picast project try to provide miracast display sink/reciever functionarity on Raspberry Pi Zero W. There is no certification from WiFi Alliance, and it is built upon try-and-error basis with existent devices, there is no gurantee to compliance to WiFi alliance specifications.

Modules

picast consist with several modules.

  • picast.dhcpd provide dhcp server function by running external udhcpd daemon with custom configuration.
  • picast.discovery provide an interface to mDNS/SD network to register and query display sink and source.
  • picast.player provide a RTP movie and audio player, supporting H.264 and AC3/AAC/LPCM audio codecs.
  • picast.settings is an ini file loader and configration provider.
  • picast.video checks platform and provide proper wfd-video-formats parameter for miracast negotiation.
  • picast.wifip2p setup wpa_supplicant to accept connection from miracast source.
  • picast.wpacli provide methods to configure wpa_supplicant through wpa-cli command line.
  • picast.picast is a core module to define controller and communicator with miracast source throught RTSP.

GStreamer

picast depends upon GStreamer video/audio handling framework and its python bindings. picast uses ‘OpenMAX’ codec API to decode H.264 video container.

Threads

picast uses threading technic to realize a controller communication through RTSP and RTP player control

Tests

There are several unittests for functions but it is not enough and there is possibility to exist defeat.

Logging

picast defines module level logger and output many debug messages.

Settings

There are several configurations you can customize in settings.ini.

Section [logging]

logger

‘logger’ is a name of logging. You can change if you want. It is used for logging.getLogger(<name>) as a its <name>.

config

‘config’ is a filename of logging configuration. It should be ini style configuration that syntax is described in configuring logging section of python manual.

Section [network]

myaddress

‘myaddress’ is an IPv4 address to attach WiFi-P2P wifi device.

peeraddress

‘peeraddress’ is an IPv4 address to lease to source device by dhcp server.

netmask

‘netmask’ is an IPv4 netmask when leasing address.

rtsp_port

‘rtsp_port’ is a port to use for negotiation between sink and source.

rtp_port

‘rtp_port’ is a port to use displaying source image onto sink monitor.

Section [p2p]

device_name

‘device_name’ is used to display a name of receiver name on source device.

device_type

‘device_type’ is used to specify a WiFi-P2P device_type.

group_name

‘group_name’ is used to specify a WiFi-P2P Group name.

wps_mode

‘wps_mode’ is used to specify which mode for WPS configuration. pbc is for ‘Push the Button’ and pin is for static PIN used.

pin

‘pin’ for wps_mode=pin configuration.

timeout

‘timeout’ for wps_mode=pin configuration.

Section [player]

name

‘name’ of player, one of vlc or gst is accepted.

Section [gst]

decoder

‘decoder’ is a gst plugin name to decode H.264/H.265 video. omxh264dec is recommended for Raspberry Pi video chip. It is used when player name is specified as gst.

Section [wfd_parameter]

wfd_audio_codecs

It is used as a value for wfd_audio_codecs parameter when negotiation. default value is AAC 00000001 00, LPCM 00000002 00

wfd_connector_type

It is used as a value for wfd_connector_type parameter when negotiation. HDMI is 05.

Resolutions data

There is a resolutions.json file that describe Raspberry Pi video resolutions data. It is used to determine which video mode is supported in current RaPi device and monitor device.

Resolutions are retrived by tvservice command. code number is used to determine its output. mode is a WiFi Direct video mode corresponding with specified resolution.

If you want to porting picast to another device, you should create a new json file and update video.py module.

authors

PiCast is written and maintained by Hiroshi Miura <miurahr@linux.com>

Original lazycast is written by Hsun-Wei Cho and its contributors

Contributors, listed alphabetically, are:

changeLog

All notable changes to this project will be documented in this file.

Unreleased

Added

Changed

Fixed

Deprecated

Removed

Security

v0.3.2

Fixed

  • Fix ip address error for zeroconf constructor(#9).

v0.3.1

Fixed

  • Fix settings.ini not found error on distribution.

v0.3

Changed

  • Release artifacts with github actions.
  • Use setuptools_scm to automate version.
  • Packaging metadata in setup.cfg
  • Auto generate binary by build backend.

Fixed

  • Several document errors.

v0.2.4

Added

  • Comments for parameter configs.
  • Parameters Microsoft V2 extensions.

v0.2.3

Changed

  • Change class name RtspSink to RTSPSink

Fixed

  • Watching socket timeout and break connection.

v0.2.2

Changed

  • Update README to use pypi.org for distribution.
  • Refactoring RTSPSink class

Fixed

  • Fix config loading error.

v0.2.1

Added

  • Introduce [p2p] wps_mode= in settings.ini. can be ‘pbc’ ie. Push the Button, or ‘pin’
  • Add documentation for settings.

Changed

  • Add p2p_connect() and start_wps_pbc() methods.
  • Improve CLI staff.

Fixed

  • main() drop unused asyncio staff.

v0.2

Added

  • Test for python 3.7 and 3.8 - Install PyObject through pip. - Add network protocol functional tests.
  • Test typing with mypy. - dependency for gst-python-stubs and PyObject-stubs

Changed

  • Introduce RTSPTransport class to handle network connection.

Fixed

  • Bug: fails to recieve M4 message because M3 reciever can read both M3 and M4.

v0.1

  • First working release.

v0.0.1

  • Forked from lazycast.

Indices and tables