Device Configuration


Overview

If you installed a new device and booted for the first time, info-beamer will generate three partitions on the SD card.

The first is the system partition and stores all files required for booting as well as the complete system and configuration. This partition is always read-only while the device is running.

You can put configuration files on this partition to change the behaviour of the info-beamer hosted operating system.

You should ignore the two other partitions as they are not intended to be manually modified or edited by the user.

Use a configuration tool

You can either create configuration files yourself or you might use the official info-beamer OS configuration tool. Download the generated zip file and unpack it to the SD card. When updating a configuration created by that tool, be sure to delete the previous /config directory on the SD card before unpacking a new one. That way you don't have any obsolete configuration settings.

Changing an existing configuration

If your device is already running and showing content, you can change configuration values in two ways. Both of them require a short downtime of your device.

File based editing

You can unplug the device, get its SD card and edit the configuration files directly. This requires you to be at the device while editing. See below for all the different configuration files and options.

Web based editing

The latest info-beamer OS offers support for editing almost all configuration options remotely. Just go to the device detail page of the device you want to edit and use the configuration editor.

Once you're done, click on Apply configuration and reboot device and the device will save the configuration and reboot. This might take a moment as the device reinstalls the complete operating system with your changes applied to it.

If, after a reboot, the device doesn't work properly, for example if the WiFi configuration is incorrect or it can't reach the info-beamer service, it will automatically restart after 6 minutes and revert to the previous configuration.

Configuration

You can enable certain options by creating files on the first partition. This partition is the one that's visible when you insert the SD card into a Windows machine.

All configuration files are stored in the /config directory.

All files must be created with unix line endings (\n). If you're creating your configuration with a Windows text editor, make sure it does not save with \r\n endings.

Do not use windows line endings for your configuration files or they won't work! Use Unix line endings (\n) when saving your config files!

WiFi configuration

Before you decide to use WiFi, be aware that WiFi has a lot of problem sources like bad reception, regional channel policies, random connection losses, slow download speed, updated WiFi credentials, etc. If you can, please use an Ethernet connection instead.

WiFis with Captive Portals are not supported! If you see a landing page in a browser when you connect to your WiFi, info-beamer hosted won't work! See below.

2.4Ghz WiFi networks are supported on all Pis with a built-in or supported USB adapter. 5Ghz is only supported on the Pi3B+

info-beamer hosted supports WiFi. On the Raspberry Pi3, Pi3B+ or Pi Zero W you can use the built-in WiFi adapter. On all other Raspberry Pi versions the only chipset supported is RTL8188CUS. There are multiple devices with that chipset. The suggested hardware is EDIMAX EW-7811Un. It is strongly recommended to use it as other devices might advertise the required chip while using a different/incompatible one. You can purchase the EDIMAX EW-7811Un dongle for example on amazon.com or amazon.de.

To activate WiFi, create the file /config/wireless. It must consist of two lines with your SSID and password (WPA2 PSK). Example:

MyAccessPoint
MySecretPassword

When you start the device it'll use the information in this file to connect to the specified encrypted network.

If you want to connect to an unencrypted network (which is not recommended!) you can use this configuration in /config/wireless:

MyAccessPoint
NONE

So the literal NONE in the second line. Notice that WiFi tends to be unreliable if you don't have good reception. You get much better reliability by using a wired connection. If you activate WiFi, all ethernet connections are ignored.

Captive portals

There are certain wireless networks that seem to be "open". But once you connect you're supposed to enter various information using a web browser before you can actually use the network. Sometimes you have to enter a credit card number, username and passwords or confirm some terms and conditions by clicking checkboxes.

There is absolutely no standard regarding those captive portals. So it is impossible for info-beamer hosted to automate the login. You won't be able to get a proper internet connection and info-beamer hosted won't work. The only solution is to setup info-beamer hosted in a proper network environment. You might also ask your network administrator to maybe open up the network to the Pis MAC address.

Completely custom configuration

Instead of using /config/wireless you can also create the file /config/wpa.conf. If it exists it takes precedence and allows you to specify a complete wpa_supplicant.conf configuration file. If you have to refer to the /config directory within that file, be sure to use the /sd/config prefix instead as the SD card is mounted in that location.

Custom configurations allow you to configure almost every type of WiFi setup available, but you'll have to know the exact parameters required. You might want to turn on debugging.

An example configuration for a corporate 802.1x EAP / PEAP / MSCHAPV2 setup might look like this:

network = {
    ssid="<Network Name>"
    key_mgmt=WPA-EAP
    eap=PEAP
    identity="<Username>"
    password="<Password>"
    phase1="peaplabel=auto peapver=0"
    phase2="auth=MSCHAPV2"
}

Additionally you can specify multiple network blocks in a single wpa.conf file. Doing that will allow your device to roam between the two networks as it automatically tries all of them until it finds a working connection.

Automatic fallback to ethernet

Sometimes it might make sense to have a device automatically use Ethernet even if WiFi is configured. This is useful if you want to preinstall a device before shipping it to a customer without knowing which type of connection is going to be used.

If you create the file /config/prefer_wired, then the device will test for an Ethernet connection during the boot process. If available, it will be used instead of the configured WiFi.

This test is only done once while booting the device. Attaching a connection later won't switch the connection. If you know which connection a device should use, it's suggested to not use this feature as it might run into false negatives if the Ethernet doesn't work while the device boots.

WiFi Configuration Interface

If a device is unable to connect to the configured WiFi network it can automatically create its own temporary WiFi network to allow it to be reconfigured. This doesn't happen automatically unless you enable it for a device. Create the file /config/wifi_ui with the one or two lines like this:

Password
Accesspoint Name

You have to provide at least a password in the first line. The second line is optional. If it is not provided, the SSID of the WiFi configuration network will be info-beamer config (<serial>) with serial being the device serial number.

Once configured the temporary configuration WiFi network will be active in the first 10 minutes of uptime, if the device can't associate to the configured WiFi network within 60-80 seconds. So be patient: It might take a few seconds before the WiFi Configuration Interface starts. This prevents false positive were the configuration interface would start prematurely if your normal WiFi is a bit slower.

While this network is active, a small icon will blink in the top left corner of the screen and the device LED will blink in a heartbeat pattern.

You can connect to this network using the password you specified in /config/wifi_ui. Once connected, mobile devices will automatically open up a browser with the configuration website. If the automatic redirect doesn't happen, you can manually reach the page by opening http://10.0.0.1 in any browser. The configuration interface looks like this:

.

You can select any of the detected networks and enter their password. Clicking CONNECT will save the settings and reboot the device. The device will then try the new settings. If the new settings don't work, the configuration interface will be started again. If you click on Cancel, the temporary configuration WiFi will be shut down. If you click nothing, the temporary configuration WiFi will shut down automatically after 10 minutes.

The WiFi Configuration Interface is not supported on the CM3-PANEL as it's not possible to scan for WiFi networks while the WiFi adapter is in master mode.

USB file import

This feature is not yet available in the stable release of info-beamer. If you want to try out this feature you'll have to upgrade your device to the testing version of the info-beamer OS.

If you create the empty file /config/importer on your SD card, your info-beamer device will monitor attached USB drives. If you plug in an USB stick with files on it, your device will automatically import all files into its local cache.

Make sure your USB stick is formatted with the FAT32 filesystem. Otherwise the import won't work.

Your device will blindly import all files from the USB stick. You should only have files on the USB stick that you want to use in your setups.

If you later use any of the files as part of a setup, the device doesn't have to download the file from the info-beamer service as its already locally cached. The filenames you use on the USB stick don't even have to match the filenames of the assets you uploaded to the info-beamer hosted service: The syncing process will automatically detect if files are identical and can be used.

This allows you to save bandwidth in low-bandwidth environments. Together with the peer-to-peer feature you can reduce the external bandwidth requirements for large installations to almost zero if you follow these steps:

  • Make sure you enable peer-to-peer on all devices.
  • Make sure your devices can reach each other in your local network. You can verify that on the device page. There should be a green "connected" next to the Peer-to-Peer row in the "Device information" column on each device detail page.
  • Copy new content (video/image) to an otherwise empty USB stick. Make sure it is formatted using the FAT32 file system.
  • Put the USB stick into a Pi that has the USB file import feature (see above) enabled. Once you plugged in the USB stick, the red power LED of your device will start blinking in a heartbeat pattern. This means the device is importing your files. Wait until it stops blinking. You can now remove the USB stick.
  • Now upload the content to info-beamer hosted as new assets as usual.
  • Assign the uploaded assets to your devices.

If done correctly, the device you plugged in the USB stick will now make the new files available to your other devices. They will fetch them from your local device instead of using the internet connection. If you assigned content to many devices they will even start sharing and transferring the files from each other to prevent the single Pi from getting overloaded.

P2P

The info-beamer hosted OS can optionally use a peer-to-peer protocol to detect other info-beamer devices in your network.

You can enable peer-to-peer by simply creating the file /config/p2p. When a device starts, it will automatically try to detect other nearby info-beamer devices. See the security page or the blog post introducing this feature for more background information how this works.

Activating this features adds the benefits described in the next sections:

Time desync detection

If the peer-to-peer service detects other devices, all of them will be able to easily detect clock desyncs. If they detect that their time is out of sync, they will restart their NTP client and attempt to resynchronize. This benefits video wall installations as they depend on a correctly synchronized clocks.

Accelerated content downloads

If multiple devices share the same network uplink, content assigned to multiple devices at once doesn't have to be downloaded by all of your devices individually. Instead one device downloads the content from the info-beamer hosted system while other devices in your network can then fetch the content locally from that device. This greatly reduces outside network traffic as it allows your devices to share already downloaded content.

Of course doing that is completely secure. The content transferred between your devices is encrypted and verified. Learn more...

Debugging

Sometimes things just don't work and the output while booting doesn't help. In that case you can create the empty file /config/debug on the SD card. The boot process will now be a lot more verbose and will hopefully help you solve the problem.

Automatically add a device to your account

A new device will display an PIN by default once it booted up. You can use this PIN in the Register Device dialog on the device list page to manually add a device to your account.

You can also setup a device so gets added to your account automatically: Click the Download Device Connect Key button on your account page and save the resulting device-connect-key.txt file in the /config directory on the device SD card. Once that's done the device will add itself to your account when it first boots up unless it's already assigned to another account.

If the automatically added device has a serial number of an existing device in your account, it be treated as a device replacement and the new device will automatically carry over the assigned setup and location of the oldest device with the same serial number. You can use this feature to easily switch out damaged SD cards: Just add a the Connect Key to the new card and replace an existing card in one of your devices: The device will boot, automatically join your account and show the same content as before.

When you regenerate your API key, the Device Connect Key will be regenerated as well. You have to download the device-connect-key.txt file again in that case.

Static network configuration

By default the info-beamer system uses DHCP to dynamically configure network settings. If you don't have a working DHCP environment you must specify IP configuration manually.

Create the file /config/network. It must consist of four lines.

IP address
netmask
default gateway
DNS IP

For example:

192.168.1.200
255.255.255.0
192.168.1.1
8.8.8.8

Custom DNS settings

If you need to be more specific in regards to how DNS should be used, you can create the optional file /config/resolv.conf. It will be used like the traditional resolv.conf file. So you can set multiple DNS servers.

DNS over HTTPS

You can optionally use DNS over HTTPS to resolve DNS queries. Instead of using the DHCP provided, default or set DNS servers, the info-beamer hosted OS will the query the DoH servers from either Google or CloudFlare.

To use this feature, just place an empty file named /config/dnscrypt on the SD card.

This feature is still experimental. DNS is quite important for your devices. Right now it's recommended to only activate this feature on non-production devices.

Custom hostname

You can assign your device a custom hostname. Just put the hostname into the file /config/hostname. The hostname will be shown in the prompt - which isn't reachable unless you either activate SSH or allow the local shell. The hostname will also be used during DHCP requests to suggest a device hostname. Of course your DHCP server is free to ignore this suggestion.

If you don't specify a hostname, info-beamer-<SERIAL> is used by default.

Custom NTP Servers

By default your device automatically uses the NTP service specified by your DHCP server. If you don't use DHCP or your DHCP server doesn't specify an NTP server IP address the device will instead use the debian NTP servers. If you want to manually configure other NTP servers you can specify those by creating a new file /config/ntp. It must consist of a single line with NTP server hostnames separated by spaces. So a custom configuration looks like this:

0.europe.pool.ntp.org 1.europe.pool.ntp.org

Specify audio target

By default info-beamer outputs audio using the RCA jack on the Pi. If you want to output audio using HDMI, create the file /config/audio and add a single line containing hdmi to it. If you want to force using the RCA jack, set its content to local.

Force output resolution

Normally the Pi automatically detects the resolution of attached screens. If you have a special setup where EDID does not work or you want to force a resolution you can specify it in the the /config/tvservice.

The file must consist of a single line with the intended mode. All available modes can be seen on http://www.raspberrypi.org/documentation/configuration/config-txt.md.

There are two different HDMI output groups: CAE and DMT. You specify the mode by specifying the HDMI output group and the intended HDMI mode. An example file might look like this:

DMT 82

This will set the output to 1920x1080 with 60Hz.

Custom resolution

You can force the Pi to output any custom resolution. First you'll have to define the resolution using the /config/userconfig.txt file. Add a line like this:

hdmi_cvt=768 576 60 1 0 0

The parameters to hdmi_cvt as as follows:

hdmi_cvt=<width> <height> <framerate> <aspect> <margins> <interlace> <rb>
width width in pixels
height height in pixels
framerate framerate in Hz
aspect aspect ratio 1=4:3, 2=14:9, 3=16:9, 4=5:4, 5=16:10, 6=15:9
margins 0=margins disabled, 1=margins enabled
interlace 0=progressive, 1=interlaced
rb 0=normal, 1=reduced blanking

Then create the /config/tvservice file with the following content to force the defined solution:

DMT 87

Force composite output

Usually an info-beamer device always activates HDMI output even if no HDMI screen was detected. If you want to force analog composite output instead, you can use the /config/userconfig.txt file for that. Create it and add the following two lines:

hdmi_force_hotplug=0
hdmi_ignore_hotplug=1

Activate SSH

Create the file /config/authorized_keys. This file follows the usual authorized_keys file format. So it contains one or many SSH public keys that will be allowed to SSH as root into the device.

If you add this file, info-beamer will start the SSH daemon and you'll be able to login as root with the specified keys.

You can verify the SSH host key by visiting the device detail page for a device. The SSH fingerprint is available in the Device settings sidebar.

SSH should only be used locally while developing a package. Leaving SSH accessible in a production device is always a risk as it exposes an additional attack surface.

Do not use SSH to sync content to your device. Always deliver content through a package. That way it can be verified, cached and survives device reboots.

Activate Remote Syslog

Normally the last 1MB of logging information is stored in RAM. It is lost during reboots. If you want to store log information permanently, you can activate Remote syslog support. This will send the log to the specified host.

Generate the file /config/remote_syslog and specify the address of your syslog server. The device will then send logging information there.

To see if logs are sent, start

netcat -l -p 514 -u

on the specified machine. You should see logs information.

The log contains sensitive information and is sent unencrypted. Use with care!

Expose info-beamer ports

By default, the running info-beamer process is not reachable from other hosts. Only from local processes running on the same device. Before you can send information to your info-beamer nodes remotely you must configure the device to bind info-beamer to a publicly reachable address. It's almost always better to use the remote control feature instead.

Create the file /config/bind_address. If you want info-beamer to be reachable from external hosts, put 0.0.0.0 in that file.

Once you make info-beamer accessible other programs can talk to info-beamer using TCP or UDP on port 4444 and connect to nodes in the running visualization code. Depending on the running code this might expose functions that might be designed to trust their input and to be reachable from the local device only.

Be sure to understand the consequences of exposing info-beamer to your network.

Dev Mode

info-beamer hosted allows you to rapidly develop packages using a feature called dev-mode. It allows you to push code and data directly to an info-beamer devices from your development machine. That way you can instantly see changes you make to code or assets. This feature can be enabled by creating the file /config/dev-mode.

You can use the dev-mode tool from the info-beamer package sdk repository on your development machine.

The dev-mode feature will blink an icon like this in the top-right corner of the device output to remind you that dev-mode is active and a device with the feature enabled doesn't accidentally end up in production.

Important: Never activate dev-mode on production devices or in untrusted networks! Your device can be easily taken over as anyone can push any code to your device. Only use it in a secure development environment!

VNC

The device can optionally start a VNC server. This allows you to connect to your device with any VNC client to see the device output. The Pi isn't fast enough to show its output perfectly smooth in realtime, but 2-5 fps are possible. This feature can helps you if you want to develop content on your Pi but you don't have a screen connected.

Do not enable the VNC server on production devices as it opens up a new port.

Local Shell

If you want to allow a local shell, create the empty file /config/allow_shell. This will allow you to open up a debug shell by switching to console 2 (Ctrl-Alt-F2) and then pressing Return. info-beamer will be stopped temporarily and you'll see a shell prompt. info-beamer will be restarted once you exit this shell and normal device operation will resume.

You should probably keep the local shell disabled unless you have a good reason since it offers easy access to a device for anyone with physical access.

Custom Raspberry Pi settings

You can create the file /config/userconfig.txt on the SD card and add additional options the you would normally put into the file /config.txt. This allows you to adjust options like overscan or overclocking (not recommended!). Do not make those changes in the existing /config.txt file on the SD card. It will be overwritten when rebooting. Use /config/userconfig.txt

Release Channels

The info-beamer hosted operating system has multiple release channels. The default channel is stable. It is intended for normal operation. If you want to see new features faster and don't mind if your devices might break you can use the testing channel. This channel gets updates more often and will be stable once it's ensure that it works reliably. Another channel is bleeding where you can see all the most recent updates. This is the channel all development is done in and it will break from time to time, so don't use it in production.

Switching between stable and testing is possible on the Manage menu on the device page. The previous way of switching channels through the file /config/channel is no longer supported.

Setting the output display

It's possible to specify the display to use for a Pi. By default HDMI is used. It's possible to overwrite this default setting by putting the display name/number into the /config/display file.

content of /config/display Output
0 or lcd Default LCD / HDMI
1 or tv Internal DSI LCD, like the 7" official display

Setting HDMI clock sync

If you create the file /config/hdmi_clock_sync, raw videos will play with HDMI clock sync set. This means that the HDMI clock will be adjusted to the HDMI frame rate. Some screens have problems with this feature, so it's usually not recommended to use it.

Keep attached HDMI screen on

Recent versions of info-beamer hosted OS can monitor the attached HDMI screen and can try to turn it back on if they detect that the screen has been turned off. Just create the empty file /config/hdmi-keep-on on the SD card and start your device.

Custom Branding

When info-beamer OS is booting up you see a big info-beamer welcome screen by default. You can add your own content there easily by just adding files to /config.

If you just want a static image you can put a JPG image on the SD card in /config/branding.jpg. It fill be displayed fullscreen instead of the default info-beamer logo. If you want to make a good impression make sure that your image has the same aspect ratio or better the same resolution as your screen.

You can also add a video intro instead of a static image. Just add an H264 MP4 video in /config/branding.mp4. It will be loaded and looped while the device is starting up.

Do not put too big video files (>10MB) onto the SD. Updating the operating system will fail if there is not enough free space remaining.

In both cases the default instructions ("Use this PIN...") will be displayed as a smaller scale at the bottom of your screen.

Additionally your can add a /config/branding.ppm image to the SD card. It will replace the default logo shown at the top left corner right after the device started. It's recommended that you use an image with a maximum height of 90 pixels. You can use imagemagick to convert images to the PPM format.