:!: **OBSOLETE**: This documentation is obsolete, and refers to older versions of PIXILAB Player. Find the current documentation [[blocks:player-setup|here]].

====== PIXILAB Player ======
PIXILAB Player is free software that makes a player or interactive kiosk out of an NUC or other PC-style computer, for use with Blocks as a Display Spot. It's based on the excellent [[http://porteus-kiosk.org/|Porteus Kiosk]] project.

This article describes how to make such a player. You will need a wired Internet connection with automatic network configuration (DHCP) for the installation process. 

===== PIXILAB Player System Requirements =====
We recommend using an NUC as the player. For basic applications in HD resolution, you can choose a low-cost, Celeron based model. For most applications, an i3-based model is sufficient. For demanding applications, select an i5 or i7-based model.

The player only needs CPU and a minimum of 4 GB of RAM to be installed. No hard drive/SSD is required. For 4k video playback, two RAM modules are recommended to optimize the memory bandwidth. We recommend RAM modules such as SO-DIMM at 2666Mhz or better (but also check manufacturer's recommendations).

===Additional storage medium for Block Caching and Offline use===
To use the Block Caching feature, an additional storage device is required.
  * Internal SSD is recommended för production, providing fast and reliable storage.

:!: Due to unpredictable performance it is not recommended to use the following devices even though they technically may work. 

  * SD card of the SDHC type, up to 32GB. **NOTE**: SDHX cards or cards larger than 32GB do //not// work.
  * USB 3.x memory stick.


===== Getting Started =====
To create a player, you need a USB stick at least 8GB in size, which will become your bootable player.

  - [[https://www.balena.io/etcher/|Download Etcher]], which you will use to "burn" an ISO file onto the USB stick.
  -  [[https://pixilab.se/outgoing/blocks/player-maker/ISO/PIXILAB-player-maker.iso|Download the player ISO image]].
  - Use Etcher to transfer the ISO image onto your USB stick.
  - Connect a monitor to the target computer (NUC or other suitable model).
  - Connect the target computer to a wired network with Internet access. 
  - Move the USB stick to the the target computer
  - Start the target computer, making it boot from the USB stick.

If the computer doesn't boot from the USB stick, you need to enter its BIOS and change its boot settings so that it can boot from USB. You may also need to turn off any //Secure Boot// option. Once target computer has started, you should see a screen similar to this:

{{ :blocks:player:idcode.png?nolink&600 |}}

Using a web browser on another computer (e.g., your laptop), go to the [[https://pixilab.se/outgoing/blocks/player-maker|URL displayed on the screen]]. This should lead you to a webpage looking like this:

{{ :blocks:player:welcome.png?nolink&600 |}}

Enter the ID shown on the target computer's screen, and press Continue. After accepting the Google Chrome license terms, you will be able to configure your PIXILAB Player.

{{ :blocks:player:configure1.png?nolink&600 |}}

In most cases, only three settings need to be specified: 

  * The domain or IP address of the Blocks server.
  * The keyboard layout (if a physical keyboard is to be used).
  * Whether to show the mouse cursor (if you intend to connect a mouse to the display spot).

:!: **NOTE:** Enter just the IP address or domain name in the text field. Do not append "/spot" or any other path. When using our Linux based server image, you don't need to specify a port number. However, if you're running Blocks on your Mac or Windows computer, also append any non-standard port number separated by a colon, e.g. //:8080//

Once you are happy with the configuration, press "Save and continue". The target computer must now reboot for the settings to take effect.

:!: **IMPORTANT:** Leave the webpage open until the reboot has completed.

{{ :blocks:player:reboot.png?nolink&600 |}}

Once the target computer has rebooted and finished updating, you can close the webpage. You can now connect the player to your Blocks network. An additional reboot may be required to establish the server connection.

Additional options can be accessed by checking “Show advanced settings”. Some of these options require more details to be specified, and may reveal additional options. Hover over an option to learn more about it, its use cases and possible values.

{{ :blocks:player:advanced.png?nolink&600 |}}

=== Blocks Server Connection Type ===

If you're exposing your Blocks server to the Internet, you're strongly advised to use an encrypted server connection (HTTPS). Note that this requires a domain name and an associated certificate to be installed on your Blocks server.

If players are used only on an intranet, and don't connect over the Internet, you do not need to run HTTPS on those players. In general, unless explicitly forbidden by your server's configuration, players can access the server over HTTP even when the editor and other secure endpoints use HTTPS.

=== Block Caching ===

If selected, PIXILAB Player allows the default block (the one dragged onto the spot) to be cached on the player. This requires an additional storage medium to be installed on the player, such as an SD card. This storage medium will be formatted for use for block caching the first time the player is started with this storage medium installed. Once enabled, the default block, including all its media, will be stored on the player. This greatly reduces the amount of network traffic required for playing the block. Furthermore, it allows the block to play even without a server connection (assuming the block doesn't depend on any server functionality).

:!: **NOTE**: A separate license is needed on your Blocks server to use Block Caching.

=== Hardware Accelerated Video Playback ===

Enables hardware-assisted video decoding on hardware that supports this. This may improve video playback performance, but may in some cases cause other problems or stability issues, so make sure you test on representative hardware and content before deplying players with this function enabled.

=== Network Connection ===

We strongly recommend that you use a hardware network connection (Ethernet) whenever possible. However, if you must use a wireless WiFi connection, you can enable that here. When enabled, you must then specify the network name (SSID) and password for accessing the network. 

=== Timezone ===

If you need to access local time on the player (e.g., for some custom web content), select the local time zone where the player will be used.

=== NTP Server ===

If you specify a timezone to access local time on players, you may also want to specify a custom time server used to set the clock in the player. If not specified, a default NTP server will be used (pool.ntp.org).

=== Custom configuration file ===

This is an **unsupported** option intended for advanced users. If you do not fully understand how to use "custom configuration files", you should **NOT** use this option. This option is further described [[blocks:player-setup:custom-config|here]].

==== Making Multiple Players with the same Configuration ====
Etcher can be used to clone the USB stick you just made, for use on other players. Using Etcher, you can also flash several USB drives at the same time.

===== Using PIXILAB Player =====

Connect the computer to your the network used by the Blocks server. For the above settings to work, you need to have at least a DHCP server on this network (which may be the one built into the [[blocks:server:creating_a_server|Blocks Linux Server]], or a separate one as often built into routers and gateways). Allow the player to restart and connect to the network. A browser window will open, attempting to access the specified URL (e.g., ''http://pixi.guide/spot'' in the example above). If everything works as expected, you should see the PIXILAB logo on screen with an ID string below, allowing you to add it as a Display Spot to Blocks.

==== Power Management ====

When used with Blocks 2.2 or later, you can control the power of the player as well as the attached display. This works with most modern NUC models. In order to power up the player, make sure "wake on LAN" is enabled. This is specified in the configuration file above, but on some PCs this must also be enabled in the BIOS settings.

The display's power can be controlled in either of two ways:

  * If the display supports CEC control (often called something else by display manufacturers), make sure this feature is enabled in the display's or TV's menu settings.
  * If you're using a computer-style display, it may not support CEC. Instead it will typically turn itself off and on automatically as the computer is turned off/on. Make sure to enable this automatic power management feature of our display.

If you want to use the CEC method, you need to enter the BIOS settings of the NUC. Navigate to ADVANCED,  DEVICES, ONBOARD DEVICES. Enable //HDMI CEC Control// and set //Auto Turn On/Off TV// as shown below. When set in this way, the NUC will tell the TV to turn on and off in unison with itself.
 
{{ :blocks:porteus:intel_nuc_bios_cec_options.png?800;nolink |}}

To make sure your NUC-based display spot restarts after a power failure, in BIOS settings select "Last State" under Advanced, Power, Secondary Power Settings, After Power Failure.
{{ :blocks:porteus:intel_nuc_bios_power_options.png?800;nolink |}}

==== Network Boot from the Blocks server ====

If you're using our [[blocks:server:creating_a_server|Linux based server]], you can configure the server so that players can be booted over the network (PXE boot). This has the following advantages:

  * No USB stick is needed for each player.
  * The player resides only on the server, making it easy to update.
  * The configuration of all players also resides in a single place, making it easier to apply changes without making new USB sticks.

:!: To use this feature, your player PCs must support the UEFI standard for network booting.

Before attempting to boot the player from the server, make a USB stick as described above, and make sure your player works properly.

To enable network booting of you player, do the following (where individual steps may vary depending on the BIOS in the player computer):

  * Open the player's bios settings by pressing the appropriate key during startup.
  * Select "Boot USB Devices First" to make it boot from USB if one is attached.
  * Select "Boot Network Device Last" to make it boot from the server if no USB key is connected.
  * Select "Unlimited Boot to Network Attempts" to keep retrying if server can't be reached.
  * Disable "legacy boot".
  * Disable "secure boot".
  * Select "UEFI:LAN:PXE" as the preferred boot device.

Follow [[blocks:server:pxe-boot|this guide]] to configure your Blocks server for network booting.

===== Video instructions =====

[[blocks:video_overview:pixilab_player|Pixilab player video instructions]]