Advanced Configuration for 3G / 4G / LTE modems

Most modems will work out of the box just by plugging in your modem and configuring any required information (such as APN, username, password, and sim-card PIN).

Nevertheless, there are cases where your modem might not be recognized by the system as a modem. This guide is for advanced (Linux) users only. Do not hesitate to reach out in case your modem is not working out of the box.

USB mode-switching

Most USB modems usually appear as a CD-ROM or a Mass Storage Device, so that any required software can be included with the USB module itself. Usually, after the software installation, the modem will switch to modem mode and the system will recognize it as a USB modem device. This process is called USB mode switching. On Raspbian (the Yodeck SD card image is based on Raspbian), this is internally handled by the udev manager and usb_modeswitch package. If a modem has been mode-switched, it should appear in the system under the /dev directory as ttyUSB0, ttyUSB1, etc., or as cdc-wdm0.

There are cases where some devices may not automatically switch to the correct USB mode after plugging in. This may happen for newer devices or for devices that are mode-switched to the wrong USB mode. Using the Advanced Configuration field you can provide a usb_modeswitch configuration for your specific device.

For example:

[[12d1:1f01]]
TargetVendor=0x12d1
TargetProductList="1442"
MessageContent="55534243123456780000000000000011062000000100000000000000000000"

The above configuration will switch the recognized USB device with ID 12d1:1f01 to the target device with ID 12d1:1442, using the MessageContent.

Getting the ID of the unswitched device

Get the ID of the device before any mode switching is required, to be able to search the Internet for the correct MessageContent for your device.

  1. SSH to the player (Connecting to the player via ssh)
  2. Make sure the modem is not plugged in
  3. Run sudo systemctl stop udev
  4. Plugin your modem
  5. Run lsusb to get a list of the connected USB devices along with their IDs. You should be able to identify your device and get its ID.
  6. Search for usb_modeswitch and the device ID, to find a working usb_modeswitch configuration
  7. Reboot the player
  8. Create the configuration in the above format

Udev rule

If the un-switched device is not switched even if a custom mode-switching configuration exists, it is probably not matched by any udev rule, so the mode-switching is not triggered.

If a custom udev rule is required to match the un-switched device, it can be provided like this:

[[udev]]
ATTR{idVendor}=="12d1", ATTR{idProduct}=="1f01", RUN+="usb_modeswitch '%b/%k'"

Custom Network Manager connection profile

The player will use the Network Manager to handle the modem connection. The default configuration of the Network Manager is used for the modem connection profile. If a connection requires any extra special configuration, there is the option to provide the exact Network Manager configuration using the Advanced Configuration field. You can provide the configuration for the connection like this:

[[network]]
[connection]
id=custom
uuid=74dbed2d-5152-4928-82e1-ad41669f3be5
type=gsm

[gsm]
number=*99#
pin=1234
apn=apn.example.com

[ipv6]
method=auto

[ipv4]
method=auto

The connection name must always be “custom” as this name is used internally by the player.

You can find more about the available configuration options for the connection profile in the following URLs:

Complete Configuration

You can combine both configurations (USB mode-switching and custom Network Manager configuration) into a single configuration that can be used directly in the Advanced Configuration field.

For example:

[[12d1:1f01]]
TargetVendor=0x12d1
TargetProductList="1442"
MessageContent="55534243123456780000000000000011062000000100000000000000000000"

[[network]]
[connection]
id=custom
uuid=74dbed2d-5152-4928-82e1-ad41669f3be5
type=gsm

[gsm]
number=*99#
pin=1234
apn=apn.example.com

[ipv6]
method=auto

[ipv4]
method=auto

[[udev]]
ATTR{idVendor}=="12d1", ATTR{idProduct}=="1f01", RUN+="usb_modeswitch '%b/%k'"

Any text after the [[network]] header will be treated as the configuration for the Network Manager.

Any text after any [[xxxx:xxxx]] header where x is a lowercase hexadecimal digit, will be treated as the usb_modeswitch custom configuration.

Any text after the [[udev]] header will be treated as a custom udev rule.