TourBox Elite → OSC Bridge

Bridge Python qui lit les événements du TourBox Elite et les retransmet en OSC.

Deux approches sont fournies selon l'OS et la configuration :

Script	Méthode	macOS + TourBox Console	Linux / Windows
tourbox_log_osc.py	Log file tail	✅ Recommandé	❌
tourbox_osc_bridge.py	Série direct	❌ (port monopolisé)	✅

---

Contexte technique

Sur macOS, TourBox Console monopolise le port USB/série du TourBox Elite. Toute tentative d'accès direct (pyserial, Serial DAT dans TouchDesigner, dtrace) échoue car le pilote CDC est verrouillé.

La solution de contournement : TourBox Console écrit tous les événements de touches dans son fichier de log. Le script tourbox_log_osc.py surveille ce fichier en temps réel et retransmet chaque événement via OSC.

---

Prérequis

pip install -r requirements.txt

Ou individuellement :

pip install python-osc        # requis pour tourbox_log_osc.py
pip install python-osc pyserial   # requis pour tourbox_osc_bridge.py / tourbox_sniff.py

---

Utilisation — macOS (recommandé)

1. Ouvrir TourBox Console

TourBox Console doit être ouvert et actif — c'est lui qui génère le log.

2. Lancer le bridge

python3 tourbox_log_osc.py

Avec des paramètres personnalisés :

python3 tourbox_log_osc.py 127.0.0.1 9000

Le script affiche chaque événement OSC envoyé :

TourBox Elite → OSC Bridge
  Log : /Users/vous/Library/Application Support/TourBox Console/tourbox.log
  OSC : 127.0.0.1:9000
  Ctrl+C pour quitter

  OSC → /tourbox/knob  1
  OSC → /tourbox/knob  0
  OSC → /tourbox/c1    1
  OSC → /tourbox/c1    0

---

Utilisation — Linux / Windows (accès série direct)

python3 tourbox_osc_bridge.py [port] [osc_host] [osc_port]

# Exemples :
python3 tourbox_osc_bridge.py
python3 tourbox_osc_bridge.py /dev/ttyUSB0
python3 tourbox_osc_bridge.py /dev/ttyUSB0 127.0.0.1 9000
python3 tourbox_osc_bridge.py COM3 127.0.0.1 9000        # Windows

Pour découvrir le port série de votre TourBox :

• macOS : ls /dev/tty.usbmodem*
• Linux : ls /dev/ttyACM* /dev/ttyUSB*
• Windows : Gestionnaire de périphériques → Ports (COM et LPT)

---

Adresses OSC

Bridge log (tourbox_log_osc.py)

Toutes les adresses suivent le format /tourbox/<contrôle> avec la valeur 1 (appui) ou 0 (relâchement).

Adresse OSC	Valeur	Contrôle
/tourbox/a	1 / 0	Bouton A
/tourbox/b	1 / 0	Bouton B
/tourbox/c1	1 / 0	Bouton C1
/tourbox/c2	1 / 0	Bouton C2
/tourbox/side	1 / 0	Bouton SIDE
/tourbox/top_bar	1 / 0	Barre supérieure
/tourbox/knob	1 / 0	Knob (appui)
/tourbox/scroll	1 / 0	Scroll wheel (appui)
/tourbox/wheel	1 / 0	Grande molette (appui)
/tourbox/up	1 / 0	D-pad haut
/tourbox/down	1 / 0	D-pad bas
/tourbox/left	1 / 0	D-pad gauche
/tourbox/right	1 / 0	D-pad droite
/tourbox/switch	1 / 0	Switch

Limitation connue : Le log ne reporte que l'état actif/inactif des contrôles, pas la direction de rotation des encodeurs (knob, scroll, wheel). Il est impossible de distinguer CW de CCW via cette méthode. Voir Contournement encodeurs.

Bridge série (tourbox_osc_bridge.py)

Adresse OSC	Valeur	Contrôle
/tourbox/button/<name>	1 / 0	Boutons (top, tall, short, side, c1, c2…)
/tourbox/knob/<name>	+1 / -1	Encodeurs rotatifs avec direction (scroll, knob, dial)
/tourbox/dpad/<name>	1 / 0	D-pad (up, down, left, right)
/tourbox/raw	[b0, b1, b2]	Paquets non mappés

---

Setup TouchDesigner

OSC In CHOP

Paramètre	Valeur
Port	9000
Active	ON

CHOP Execute DAT (optionnel)

def onValueChange(channel, sampleIndex, val, prev):
    name = channel.name  # ex: "tourbox_knob"

    if 'knob' in name and val == 1:
        print("Knob appuyé")

    if 'c1' in name:
        print(f"C1 : {val}")  # 1 = press, 0 = release

Dans TouchDesigner, les / des adresses OSC sont remplacés par _ dans les noms de channels (ex: /tourbox/c1 → tourbox_c1).

Alternative : Serial DAT direct (sans bridge Python)

Sur Linux/Windows (port série non monopolisé), il est possible de lire le TourBox directement dans TouchDesigner sans passer par un bridge Python :

• Operator : Serial DAT
• Port : ex. /dev/tty.usbmodem000000011
• Baud Rate : 115200
• Data Bits : 8, Parity : None, Stop Bits : 1
• Received Data : Bytes (raw binary)

Puis un DAT Execute ou Script DAT pour parser les paquets de 3 octets (voir CONTROL_MAP dans tourbox_osc_bridge.py).

Sur macOS avec TourBox Console actif, cette méthode échoue (port verrouillé — voir Contexte technique).

---

Contournement encodeurs

La direction de rotation (CW/CCW) n'est pas disponible via le log. Piste possible : configurer TourBox Console pour mapper chaque direction d'encodeur sur un raccourci clavier dédié (ex. F13–F18 pour les 3 encodeurs × 2 directions), puis intercepter ces touches côté Python. Cela n'a pas encore été implémenté.

---

Diagnostic

Pour observer les paquets série bruts du TourBox (Linux/Windows, ou macOS sans TourBox Console) :

python3 tourbox_sniff.py [port]

Affiche chaque paquet de 3 octets reçu :

    #  HEX                   DEC                   BIN
----------------------------------------------------------------------
    1  01 06 01              1  6  1               00000001 00000110 00000001
    2  01 06 00              1  6  0               00000001 00000110 00000000

---

IDs de contrôles connus (TourBox Elite)

Référence pour étendre le CONTROL_MAP de tourbox_osc_bridge.py :

ID (hex)	ID (dec)	Type	Nom
0x01	1	button	top
0x02	2	button	tall
0x03	3	button	short
0x04	4	button	side
0x05	5	button	scroll_press
0x06	6	button	knob_press
0x07	7	button	tour
0x08	8	button	c1
0x09	9	button	c2
0x30	48	knob	scroll
0x31	49	knob	knob
0x32	50	knob	dial
0x40	64	dpad	up
0x41	65	dpad	down
0x42	66	dpad	left
0x43	67	dpad	right

---

Fichiers

README.md                # Ce fichier
LICENSE                  # Licence MIT
requirements.txt         # Dépendances Python
tourbox_log_osc.py       # Bridge principal — macOS via log TourBox Console
tourbox_osc_bridge.py    # Bridge série — Linux/Windows accès direct
tourbox_sniff.py         # Sniffer série — diagnostic et reverse engineering
archive/                 # Scripts d'exploration (dead-ends de reverse engineering, hors repo git)

---

Licence

MIT — voir LICENSE.