Astuce : Synology DSM 7 et problème de périphérique USB

Si vous avez installé DSM 7 sur votre NAS Synology, vous avez probablement constaté que ce système d'exploitation n'est pas tendre avec les périphériques USB série. Synology a retiré du noyau une partie des pilotes qui étaient présents en DSM 6, et votre clé Zigbee, votre dongle Z-Wave ou votre lecteur de compteur électrique se retrouvent invisibles du jour au lendemain.

Si comme moi, vous utilisez votre NAS Synology comme serveur de domotique au fond de votre baie de brassage, vous aurez besoin de l'astuce que je vous présente dans cet article.

Elle repose sur le projet GitHub de Robert Klep, qui compile et publie les modules manquants pour les différentes plateformes matérielles Synology. Le dépôt couvre quatre pilotes : cp210x, ch341, pl2303 et ti_usb_3410_5052. Les deux derniers ne sont pas disponibles pour toutes les plateformes.

Avant de commencer : votre périphérique a-t-il vraiment besoin de cela ?

Synology conserve dans DSM 7 le pilote générique CDC ACM, dans /lib/modules/cdc-acm.ko. Un certain nombre de périphériques série modernes passent par cette couche et fonctionnent sans rien installer, à condition que le module soit chargé. C'est le cas de la ConBee II, par exemple.

Vérifiez donc d'abord ce que voit votre NAS :

sudo insmod /lib/modules/cdc-acm.ko
sudo lsusb -cui

Si votre périphérique apparaît avec une affectation de type ttyACM0, vous n'avez pas besoin de la suite. Si rien n'apparaît, ou si vous savez que votre matériel utilise une puce Silicon Labs, WCH ou Prolific, poursuivez.

Étape 1 : identifiez la plateforme de votre NAS

Les modules noyau sont compilés pour un couple précis plateforme matérielle / version de DSM. Il vous faut donc connaître le nom de plateforme de votre modèle. Le plus rapide est de le demander directement au NAS :

grep platform_name /etc/synoinfo.conf
uname -a

La première commande vous renvoie le nom de plateforme (braswell, geminilake, apollolake, rtd1296, etc.), la seconde la version du noyau, qui vous sera utile si vous devez ouvrir un ticket sur le dépôt. Vous pouvez aussi retrouver l'information dans la colonne « Package Arch » de la table de correspondance Synology.

Étape 2 : connectez-vous en SSH à votre NAS

Activez SSH depuis le panneau de configuration, puis connectez-vous avec votre compte administrateur.

Le port SSH sur le Synology fonctionne généralement sur un port différent du port 22 si vous avez suivi les recommandations de sécurité Synology.

Étape 3 : téléchargez les modules compilés

Rendez-vous dans le répertoire modules/ du dépôt et repérez le dossier correspondant à votre plateforme, puis à votre version de DSM. Les pilotes DSM 7.0 sont disponibles pour la plupart des plateformes, ceux pour 7.1 et 7.2 sont ajoutés progressivement. Le mainteneur indique que les modules 7.2 fonctionnent en général également sur DSM 7.3^[1].

Voici l'exemple pour mon NAS Synology DS216+II en DSM 7.1 sur une architecture Braswell :

cd /lib/modules/
BASE=https://github.com/robertklep/dsm7-usb-serial-drivers/raw/main/modules/braswell/dsm-7.1
sudo wget $BASE/ch341.ko
sudo wget $BASE/cp210x.ko
sudo wget $BASE/pl2303.ko
sudo wget $BASE/ti_usb_3410_5052.ko

Adaptez braswell et dsm-7.1 à votre configuration. Si l'un des quatre fichiers n'existe pas pour votre plateforme, wget vous le dira : ce n'est pas bloquant, seuls les pilotes correspondant à vos périphériques comptent.

Le point de vigilance est ici : le segment /raw/ dans l'URL est indispensable. Sans lui, GitHub vous renvoie la page HTML de présentation du fichier, et vous vous retrouverez avec un .ko qui n'en est pas un. Vérifiez systématiquement :

file *.ko

Vous devez lire ELF 64-bit LSB relocatable et non HTML document.

Étape 4 : configurez le chargement automatique

Les modules ne sont pas chargés seuls au démarrage, et l'ordre de chargement compte : usbserial.ko doit être en place avant les pilotes spécifiques, sinon vous obtiendrez des erreurs de symboles manquants. Le script fourni par le dépôt s'en charge :

cd /usr/local/etc/rc.d/
sudo wget https://raw.githubusercontent.com/robertklep/dsm7-usb-serial-drivers/main/usb-serial-drivers.sh
sudo chmod +x usb-serial-drivers.sh

Étape 5 : vérifiez que vos périphériques sont reconnus

Inutile de redémarrer le NAS, lancez simplement le script à la main :

sudo /usr/local/etc/rc.d/usb-serial-drivers.sh start
lsmod | grep -E 'cp210x|ch341|pl2303|usbserial'

Débranchez puis rebranchez votre périphérique, et contrôlez le résultat :

sudo lsusb -cui
ls -l /dev/ttyUSB*
dmesg | tail -20

La reconnaissance se matérialise par l'apparition d'une entrée de type /dev/ttyUSB0.

Étape 6 : exposez le périphérique à votre conteneur Docker

C'est l'étape que l'on oublie souvent quand on héberge Home Assistant, Zigbee2MQTT ou Node-RED sur son NAS. Le périphérique existe côté hôte, mais le conteneur ne le voit pas.

Commencez par ouvrir les droits sur le périphérique :

sudo chmod 666 /dev/ttyUSB0

Cette permission est perdue au débranchement et au redémarrage. Créez donc une tâche déclenchée au démarrage dans le planificateur de tâches de DSM, qui charge le module et repositionne les droits.

L'interface Docker de DSM ne permet pas de déclarer un périphérique. Il faut passer par la ligne de commande :

docker run --device /dev/ttyUSB0 ...

Ou, plus confortablement, par un fichier compose.yaml :

devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"

Ce qu'il faut retenir avant la prochaine mise à jour de DSM

Ces modules sont compilés pour une version précise du noyau. Une mise à jour majeure de DSM peut donc casser l'installation, soit parce que le noyau a changé, soit parce que le contenu de /lib/modules a été réécrit. Prenez l'habitude de vérifier la présence de vos périphériques après chaque montée de version, et gardez le lien du dépôt sous la main.

C'est le prix à payer pour cette approche : elle fonctionne bien, mais elle reste en dehors du périmètre supporté par Synology.

En cas de problème

• Erreur « Unknown symbol in module » : dans la quasi-totalité des cas, vous avez téléchargé du HTML au lieu du binaire. Reprenez l'étape 3 et le contrôle avec file.
• Rien ne se charge : lancez les insmod un par un pour lire le retour du shell, en commençant par usbserial.ko.
• Mauvaise plateforme : un module compilé pour une autre architecture ne se chargera pas. Revérifiez la sortie de grep platform_name /etc/synoinfo.conf.
• Le dépôt ne couvre pas votre cas : il ne fournit que des pilotes série. Pour les adaptateurs Ethernet USB, orientez-vous vers le projet r8152 de bb-qq.

Voilà. Ce dépôt m'a sorti d'affaire à l'époque où il était encore confidentiel ; il dépasse aujourd'hui les six cents étoiles sur GitHub, ce qui en dit long sur le nombre de personnes que DSM 7 a laissées sur le carreau.

J'espère que cet article vous a été utile et n'hésitez pas à passer dire bonjour sur le Discord Geeek.

---

1. Le dépôt a également récupéré, en octobre 2022, l'ensemble des modules qui étaient publiés sur le site Jadahl.com avant sa disparition. ↩︎

---