Référence du protocole série de la Brainbox

La Brainbox reçoit les données des appareils Podcatcher via le BLE et les expose sous forme de frames CSV sur une connexion USB serial. Les installations interactives, les bornes et les logiciels sur mesure peuvent lire ces frames pour réagir aux actions des visiteurs en temps réel.

Connexion physique

Paramètre	Valeur
Interface	USB Serial (CDC)
Line delimiter	\r\n (CR+LF)
USB Vendor ID	0x2dcf
USB Product ID	0x6003

Connectez la Brainbox à un ordinateur via USB. Elle apparaît comme un port série (COM) standard — aucun pilote spécial n’est nécessaire sur les systèmes d’exploitation modernes.

Commandes de la console

Après avoir ouvert le port série, activez la console de la Brainbox et activez les types de frames dont vous avez besoin :

<CR>                        ← send a carriage return (0x0D), wait 300 ms
console tracking 1<CR>      ← enable Tracking V2 frames, wait 200 ms
console interactive 1<CR>   ← enable Interactive V1 frames, wait 200 ms
version<CR>                 ← response: "version: 2.5.1"

Astuce

<CR> désigne un seul caractère de retour chariot (hex 0x0D). Dans la plupart des terminaux série, il suffit d’appuyer sur Entrée. En code, envoyez \r (par exemple serial.write("console tracking 1\r") en Python).

Commandes disponibles

Command	Fonction
console tracking 1	Activer la sortie Tracking V2
console tracking 0	Désactiver la sortie Tracking V2
console interactive 1	Activer la sortie Interactive V1
console interactive 0	Désactiver la sortie Interactive V1
console syncdock 1	Activer les frames Basecamp (pas encore dans le firmware — voir AVS-147)
version	Interroger la version du firmware
help	Lister toutes les commandes disponibles

Note

Les réponses de la console telles que version:, console *:, ble, BLE scan:, serial:, Sync OK, Brainbox, tracking:, error et ok ne sont pas des dataframes — votre parser doit les ignorer.

Structure du contenu dans le CMS

Pour comprendre les données des frames, il est utile de savoir comment le contenu est organisé dans le Guide-ID CMS :

Site
 └── Tour
      └── Stop
           └── Clip (audio file + optional Interactive Clip Id)

• Un site comporte un ou plusieurs tours
• Un tour contient un ou plusieurs stops
• Un stop contient un ou plusieurs clips — un clip est le contenu réel, généralement accompagné d’un fichier audio lié
• Chaque clip possède un Interactive Clip Id optionnel (1–65535) qui l’identifie de manière unique pour les configurations interactives

La valeur clipIdUser dans les frames ci-dessous correspond à cet Interactive Clip Id. Vous la configurez par clip dans le CMS, sous les paramètres du clip.

Comment les clips sont déclenchés

Un clip commence à être lu sur le Podcatcher de l’une des manières suivantes :

• Beacon scan — le visiteur scanne manuellement un beacon à un stop
• UWB auto-trigger — le visiteur entre dans une zone et le Podcatcher se déclenche automatiquement en fonction de la proximité (distance UWB)
• Clip flow navigation — le visiteur appuie sur les boutons (Up, Down, Left, Right) pour naviguer dans le clip flow au sein d’un stop (par exemple des choice clips avec plusieurs branches)

Chaque fois qu’un clip démarre, la Brainbox envoie un frame avec l’Interactive Clip Id correspondant — quelle que soit la manière dont le clip a été déclenché.

Types de frames BLE

Tous les frames arrivent sous forme de lignes CSV sur le port série. Le premier champ (version byte) détermine le type de frame.

Tracking V2 — version 66 (0x42)

Envoyé environ une fois par seconde pour chaque appareil à portée. À utiliser pour le suivi en temps réel de la position des visiteurs, la surveillance de la batterie et l’état des boutons.

66,pp009071,0xA1B2C3D4E5F60718,1001,150,3700,0x0004,0x0000

#	Field	Type	Exemple	Description
0	version	decimal	66	Toujours 66
1	deviceSerial	string	pp009071	Numéro de série du Podcatcher (pp + 6 chiffres)
2	visitorId	hex	0xA1B2C3D4E5F60718	16 caractères hex (8 octets) — 0x0000000000000000 = inactif
3	clipIdUser	decimal	1001	Interactive Clip Id du dernier clip activé (0 = aucun)
4	lastTriggerDistance	decimal	150	Distance UWB en cm (0 = aucun déclenchement)
5	batteryMv	decimal	3700	Tension de la batterie en mV
6	keysLast	hex	0x0004	Derniers boutons pressés (bitmask)
7	keysHeld	hex	0x0000	Boutons actuellement maintenus (bitmask)

Attention

Les champs 6 et 7 (keysLast, keysHeld) sont encodés en hexadécimal — notez le préfixe 0x dans la sortie. Tous les autres champs numériques sont en décimal.

Bitmasks des boutons

Bit	Hex	Button	Description
0	0x0001	Down	Bouton bas
1	0x0002	Right	Bouton droite
2	0x0004	Center	Bouton centre
3	0x0008	Up	Bouton haut
4	0x0010	Left	Bouton gauche
12	0x1000	Volume Up	Augmenter le volume d’un cran
13	0x2000	Volume Down	Diminuer le volume d’un cran

Interactive V1 — version 161 (0xA1)

Envoyé chaque fois qu’un clip commence à être lu sur un Podcatcher — qu’il soit déclenché par un beacon scan, un UWB auto-trigger ou une clip flow navigation. Chaque frame vous indique :

• Quel appareil a déclenché (deviceSerial)
• Quel visiteur l’utilise (visitorId — unique par session)
• Quelle langue a été sélectionnée (NL, EN, DE, FR, ES, IT)
• Quel clip a été déclenché (clipIdUser — l’Interactive Clip Id configuré dans le CMS)
• Quel armed code a été défini par le Podcatcher (requestedVideoCode — généralement un code vidéo AV-Sync)
• Combien de déclenchements ce visiteur a eus jusqu’à présent (sequence)

161,pp009071,A1B2C3D4E5F60718,2005,EN,7,0x0000001A

#	Field	Type	Exemple	Description
0	version	decimal	161	161 ou 160 (les deux sont acceptés)
1	deviceSerial	string	pp009071	Numéro de série du Podcatcher
2	visitorId	hex	0xA1B2C3D4E5F60718	Visitor ID (unique par session)
3	clipIdUser	decimal	2005	Interactive Clip Id du clip déclenché
4	language	string	EN	Code langue de 2 caractères issu du fichier de déclenchement (NL, EN, DE, FR, ES, IT)
5	sequence	decimal	7	Compteur qui s’incrémente à chaque déclenchement, repasse à zéro après 255
6	requestedVideoCode	hex	0x0000001A	Armed code — généralement un code vidéo AV-Sync (0x00000000 = aucun)

Exemple : scénario d’un écran interactif

Un visiteur passe devant un écran interactif avec son Podcatcher. L’écran reçoit :

161,pp009071,0xA1B2C3D4E5F60718,2005,EN,7,0x0000001A

L’écran sait désormais instantanément :

• Visiteur 0xA1B2C3D4E5F60718 → reconnaissable au prochain écran également
• La langue est l’anglais → afficher des sous-titres ou du texte en anglais
• Clip 2005 → lire l’animation correspondante
• Armed code 0x1A → lire la vidéo AV-Sync attribuée à ce stop
• Déclenchement n° 7 → le visiteur est actif depuis un moment, adaptez le contenu en conséquence

Cas d’usage pour les installations interactives

Adaptation automatique de la langue Le visiteur sélectionne sa langue sur le Podcatcher. Chaque écran du musée s’adapte automatiquement — aucun écran tactile ni bouton de langue n’est nécessaire sur l’écran lui-même.

Reconnaissance du visiteur d’une salle à l’autre Le visitorId persiste pendant toute la visite. Un visiteur déclenche un écran dans la salle A, puis se rend dans la salle B — l’écran y reconnaît le même visitorId et peut personnaliser : « Bon retour, vous avez précédemment vu… » Aucune connexion ni scan de QR requis.

Projections et animations interactives Un Podcatcher arrive à portée → la projection démarre automatiquement. Plusieurs visiteurs à la fois ? Votre application voit toutes les valeurs visitorId actives dans la zone et peut adapter le contenu au nombre de visiteurs (expérience individuelle ou expérience de groupe).

AV-sync avec des écrans externes Lorsqu’un visiteur déclenche un stop, le Podcatcher arme un code (généralement un code vidéo AV-Sync). Ce requestedVideoCode est envoyé via l’interactive frame. L’écran connecté met en correspondance l’armed code et lit le contenu correspondant — aucun matériel supplémentaire (tablette, écran tactile) n’est nécessaire.

Déboguer les installations interactives

Lors du développement d’une installation interactive, utilisez un moniteur série pour :

• Déboguer en direct : voir les frames arriver en temps réel pendant que vous vous tenez devant l’écran
• Tester le changement de langue : changer la langue sur le Podcatcher et vérifier que l’écran réagit
• Contrôler le timing : les frames arrivent dans la seconde qui suit le déclenchement du beacon
• Tester avec plusieurs visiteurs : tester avec 2–3 Podcatchers simultanément et observer toutes les valeurs visitorId

Articles connexes

• Comprendre la Brainbox — ce que fait la Brainbox et comment elle fonctionne
• Configurer l’AV-Sync — configurer la lecture audiovisuelle synchronisée