Connector

De Tillor Connector is een lokale service die Tillor verbindt met fysieke apparaten in je park - zoals printers, toegangscontrollers en betaalterminals. De connector draait op een computer in je netwerk en communiceert via MQTT met de Tillor-cloud.

Hoe werkt de connector?

Tillor Cloud <-> MQTT <-> Connector (lokaal) <-> Printers / Toegangscontrollers / Terminals

De connector fungeert als brug: Tillor stuurt opdrachten via het internet naar de connector, die deze vervolgens uitvoert op de aangesloten apparaten in je lokale netwerk.

Connector installeren

De connector wordt uitsluitend als Docker-image uitgeleverd (registry.tillor.dev/tillor-public/connector:latest). Er is geen afzonderlijk installatieprogramma; je draait hem op een toestel in het lokale netwerk van het park.

Vereisten

• Een computer of server in het lokale netwerk van het park (bijv. een Raspberry Pi, NAS of Linux-server)
• Stabiele internetverbinding
• Docker en Docker Compose geïnstalleerd
• Een API-sleutel (zie hieronder)

Gegevens die je nodig hebt

Haal eerst deze twee waarden op in Tillor voordat je de container start:

Poorten

De connector luistert standaard op de volgende poorten. De HTTP-poort is configureerbaar via HEALTH_CHECK_PORT (standaard 3000); de WebSocket-poort ligt vast.

Eenvoudige setup (één replica)

Maak een map aan, zet hierin een docker-compose.yml en een .env met je gegevens, en start de container. Deze setup gebruikt een file-cache op /shared/cache zodat de toegangscontrole-gegevens herstartpersistent zijn.

services:
  connector:
    image: registry.tillor.dev/tillor-public/connector:latest
    container_name: tillor-connector
    restart: always
    environment:
      CACHE_DIR: /shared/cache
    ports:
      - "3000:3000"
    volumes:
      - ./shared:/shared
    env_file:
      - .env
    healthcheck:
      test: ["CMD-SHELL", "curl -sSf http://localhost:${HEALTH_CHECK_PORT:-3000}/health -o /dev/null || exit 1"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 10s
    security_opt:
      - no-new-privileges:true

Start met: docker compose up -d.

Geavanceerde setup (meerdere replicas met gedeelde cache)

Voor parken met veel verkeer of redundantie wil je meerdere connector-replicas draaien. In dat geval moeten ze een gedeelde cache delen, anders synchroniseren ze niet onderling. Een klein Valkey- of Redis-image voldoet:

services:
  valkey:
    image: valkey/valkey:7-alpine
    container_name: tillor-valkey
    restart: always
    command: valkey-server --appendonly yes --dir /data
    volumes:
      - ./valkey:/data
    healthcheck:
      test: ["CMD", "valkey-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3

  connector:
    image: registry.tillor.dev/tillor-public/connector:latest
    restart: always
    deploy:
      replicas: 2
    environment:
      REDIS_URL: redis://valkey:6379
    depends_on:
      valkey:
        condition: service_healthy
    volumes:
      - ./shared:/shared
    env_file:
      - .env
    healthcheck:
      test: ["CMD-SHELL", "curl -sSf http://localhost:${HEALTH_CHECK_PORT:-3000}/health -o /dev/null || exit 1"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 10s
    security_opt:
      - no-new-privileges:true

Omgevingsvariabelen

Verbinding controleren

Controleer na het starten of de connector bereikbaar en verbonden is:

1. Open http://[connector-host]:3000/health in een browser of via curl. Antwoord {"status":"ok",...} betekent verbonden; "degraded" betekent geen MQTT-verbinding.
2. Open http://[connector-host]:3000/ voor een JSON-overzicht met organisatie-ID, MQTT-status, cache-driver en synchronisatiestatus van toegangscontrole.
3. In Tillor zelf krijg je automatisch een melding ("Connector offline") wanneer de connector 5 minuten of langer geen heartbeat heeft gestuurd.

Automatische updates met Watchtower

Om de connector automatisch bij te werken (elke 15 seconden controleren op nieuwe images):

# docker-compose.watchtower.yml
services:
  watchtower:
    image: nickfedor/watchtower:latest
    container_name: watchtower
    environment:
      - TZ=Europe/Brussels
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_INCLUDE_STOPPED=true
      - WATCHTOWER_REVIVE_STOPPED=false
      - WATCHTOWER_ROLLING_RESTART=true
      - WATCHTOWER_POLL_INTERVAL=15
      - DOCKER_API_VERSION=1.43
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped

Start naast je connector: docker compose -f docker-compose.watchtower.yml up -d

HTTP-endpoints

De connector serveert een kleine HTTP-API op HEALTH_CHECK_PORT (standaard 3000). Deze is bedoeld voor health-checks van een load balancer en voor lokaal opzicht; er staan geen authenticatiegevoelige operaties op.

Gekoppelde apparaten

Via de connector kun je de volgende apparaten aansturen:

Printers

Zie de printer-documentatie voor het instellen en gebruiken van printers via de connector.

Toegangscontrollers

Slagbomen, poorten en andere toegangspunten worden gesynchroniseerd via de connector. Wijzigingen in toegangsregels in Tillor worden automatisch doorgezet naar de controllers.

Zie de controllers-documentatie voor meer informatie.

Betaalterminals

Betalingen via een gekoppelde betaalterminal verlopen ook via de connector. Tillor stuurt de betaalaanvraag naar de connector, die hem doorstuurt naar de terminal.

Problemen oplossen

Connector niet verbonden

1. Controleer of de container draait: docker compose ps.
2. Controleer de internetverbinding van de host.
3. Haal http://[connector-host]:3000/health op; bij "degraded" is er geen MQTT-verbinding - controleer TILLOR_API_URL en TILLOR_API_TOKEN.
4. Verifieer dat de API-sleutel nog geldig is in Instellingen > API-sleutels.
5. Bekijk de logs: docker compose logs -f connector.

Opdrachten worden niet uitgevoerd

1. Controleer de verbindingsstatus via GET /.
2. Bekijk de logs: docker compose logs -f connector.
3. Controleer of het betreffende apparaat (printer, controller, terminal) bereikbaar is in het lokale netwerk.
4. Bij hostname-problemen: zie de DNS-tip bij de geavanceerde setup.