Uso dell'API HTTP

Controlla Beam Bench da qualsiasi client HTTP. Stesse operazioni della CLI, ideale per le integrazioni.

L'API HTTP / WebSocket di Beam Bench è la stessa interfaccia usata dalla CLI. Se hai un caso d'uso che richiede Beam Bench in un ambiente non CLI (app web, server di integrazione, app mobile), usa direttamente l'API HTTP.

Cosa ti serve

Beam Bench installato.
L'API locale abilitata in Modifica → Impostazioni → Generale. Per impostazione predefinita è disattivata.
Un client HTTP (curl, la libreria HTTP del tuo linguaggio, Postman ecc.).

Verifica che l'API sia abilitata

Le impostazioni predefinite nella build corrente sono volutamente restrittive:

API locale: disattivata.
Porta API: 5900.
Consenti la connessione ai dispositivi di rete: disattivata. Finché rimane disattivata, il server accetta connessioni solo da questo computer.

Apri l'app desktop, vai a Modifica → Impostazioni → Generale e attiva API locale. Lascia disattivata l'opzione Consenti la connessione ai dispositivi di rete per gli script in esecuzione sullo stesso computer. Le impostazioni hanno effetto immediato.

Leggi la pagina dell'API HTTP prima di associarla alla rete su una rete Wi-Fi condivisa. L'API non dispone di autenticazione e può muovere la macchina e attivare il laser.

URL di base

http://localhost:5900/api/v1

(O l'IP LAN della tua macchina al posto di localhost, quando Consenti la connessione ai dispositivi di rete è attivato.)

Passaggi

1. Verifica che l'API sia attiva

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

Restituisce lo schema delle capacità. (Sostituisci 5900 con la porta configurata se l'hai modificata.)

2. Esamina lo stato

curl -s http://localhost:5900/api/v1/agent/state | jq .

3. Apri un progetto

curl -s -X POST http://localhost:5900/api/v1/projects/open \
  -H 'Content-Type: application/json' \
  -d '{"path":"/abs/path/to/file.lzrproj"}'

4. Esegui il rendering del progetto (senza interfaccia grafica)

curl -s -X POST http://localhost:5900/api/v1/design/render \
  -H 'Content-Type: application/json' \
  -d '{"format":"png","pixels_per_mm":4,"output_path":"/tmp/out.png"}'

5. Ottieni lo stato della fotocamera

curl -s http://localhost:5900/api/v1/camera/state | jq .

6. Esegui il rendering della sovrapposizione della fotocamera (richiede l'app)

curl -s -X POST http://localhost:5900/api/v1/camera/overlay/render \
  -H 'Content-Type: application/json' \
  -d '{"output_path":"/tmp/overlay.png","view":"fit","keep":true}'

Gruppi di endpoint disponibili

Consulta la sezione riferimento API (quando sarà compilata) per l'intera interfaccia. Gruppi principali:

/agent, capacità, stato, guida.
/camera, dispositivi, stato, acquisizione, sovrapposizione (visualizzazione, trasformazione, rendering), calibrazione, allineamento.
/design, descrizione, rendering, transazioni.
/projects, apertura, salvataggio, chiusura, livelli, oggetti, annulla/ripeti, importazione.
/export, svg, dxf, pdf, eps, ai.

Sicurezza

Il server API non dispone di autenticazione. Presuppone che la rete su cui si trova sia attendibile.

L'associazione solo a localhost limita l'esposizione alla macchina locale.
L'associazione alla rete è un'opzione separata e rende l'API accessibile a chiunque sulla stessa LAN. Abilitala solo su una rete attendibile.

Verifica del funzionamento

curl agent/capabilities restituisce JSON.
Una chiamata di rendering produce il file richiesto.