ECIService – Installation & Configuration

The ECIService is a Windows application / Docker container that acts as a bridge between Business Central (Cloud) and local printers on the network. It receives print jobs via HTTP and forwards them to the configured printer.

Overview

┌─────────────────┐        HTTPS        ┌─────────────────┐       Local       ┌─────────────────┐
│  Business Central│  ──────────────────► │    ECIService   │  ──────────────► │    Printer      │
│  (Cloud/SaaS)   │   Print Request      │  (On-Premise)   │   PDF/ZPL        │  (Windows/Zebra)│
└─────────────────┘                      └─────────────────┘                   └─────────────────┘

System Requirements

Windows Service

Requirement	Details
Operating System	Windows 10/11 or Windows Server 2016+
Runtime	.NET 10 Runtime (included in installer)
Memory	Min. 128 MB RAM
Network	Incoming connections on configured port (default: 5115)
Printers	For PDF: Windows print driver installed. For ZPL: Zebra printer reachable via TCP/IP

Docker Container

Requirement	Details
Host	Linux or Windows with Docker Engine
Image	ghcr.io/altenbrand/eciservice:latest
Ports	Port 5115 (configurable)
Print Method	ZPL only (TCP/IP) out of the box. PDF with CUPS sidecar possible

---

Installation

Option A: Windows Service (recommended for PDF + ZPL)

1. Download installer: From the internal downloads page or provided by ALTENBRAND
2. Run installation: Execute ECIService-Setup.exe as administrator
3. Choose directory: Default: C:\Program Files\ALTENBRAND\ECIService
4. Configure port: Default: 5115 (can be changed if conflicts exist)
5. Register as service: The installer automatically registers ECIService as a Windows service
6. Start service: The service starts automatically (startup type: Automatic)

Option B: Docker Container (recommended for ZPL-only)

docker run -d \
  --name eciservice \
  -p 5115:5115 \
  -e ECISERVICE_PORT=5115 \
  --restart unless-stopped \
  ghcr.io/altenbrand/eciservice:latest

For ZPL printers, the container must have network access to the Zebra printers (TCP port 9100).

Option C: Interactive Mode (development/testing only)

dotnet ECIService.dll

Starts the application as a console application with tray icon. Useful for troubleshooting and testing.

---

Configuration

appsettings.json

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:5115"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "PrintService": {
    "DefaultZplPort": 9100,
    "PrintTimeout": 30000,
    "HealthCheckInterval": 60
  }
}

Setting	Description	Default
Kestrel:Endpoints:Http:Url	IP and port for incoming connections	http://0.0.0.0:5115
PrintService:DefaultZplPort	Default TCP port for ZPL printers	9100
PrintService:PrintTimeout	Timeout in ms for a single print job	30000
PrintService:HealthCheckInterval	Interval in seconds for printer health checks	60

---

API Endpoints

Endpoint	Method	Description
/health	GET	Health check (HTTP 200 when service is running)
/printers	GET	List of all available printers on the host
/capabilities	GET	Feature discovery (supported print methods, version)
/print/pdf	POST	Print PDF label (body: JSON with Base64 PDF + printer name)
/print/zpl	POST	Print ZPL label (body: JSON with Base64 ZPL + printer IP + port)
/print/zpl/test	GET	ZPL printer connectivity test

Example: Print PDF

POST /print/pdf
Content-Type: application/json

{
  "printerName": "HP LaserJet Pro",
  "content": "JVBERi0xLjQK...",
  "copies": 1
}

Example: Print ZPL

POST /print/zpl
Content-Type: application/json

{
  "printerHost": "192.168.1.50",
  "printerPort": 9100,
  "content": "Xl5YQQpeQ0kxMw..."
}

---

Network & Firewall

Inbound (Business Central → ECIService)

Direction	Port	Protocol	Description
Inbound	5115 (configurable)	TCP/HTTP	Print jobs from BC

No HTTPS by Default

The ECIService listens on HTTP by default. For access from the internet (e.g., BC SaaS without VPN), a reverse proxy with TLS termination (nginx, Caddy, IIS ARR) should be placed in front.

Outbound (ECIService → Printer)

Direction	Port	Protocol	Description
Outbound	9100	TCP (Raw)	ZPL direct print to Zebra printer
Local	—	Windows GDI	PDF print via local print drivers

---

Troubleshooting

ECIService Not Reachable

1. Service running? → Check Windows Services (services.msc) → "ECIService" must be "Running"
2. Port open? → netstat -an | findstr 5115 → Must show "LISTENING"
3. Firewall? → Check Windows Firewall rule for port 5115 inbound
4. Health check: → Open http://<host>:5115/health in browser

Printer Not Found

1. Windows printer: Printer must be visible in Windows print management on the ECIService host
2. Exact name: Printer name in BC must exactly match the Windows printer name (case-sensitive)
3. Verification: http://<host>:5115/printers shows all available printers

ZPL Print Failed

1. Network: Zebra printer reachable via ping <ip>?
2. Port: telnet <ip> 9100 — connection must be established
3. Test print: http://<host>:5115/print/zpl/test for automated connectivity test

---

Deployment Options Comparison

Aspect	Windows Service	Docker	Interactive
PDF Print	✅ Full support	⚠️ Only with CUPS sidecar	✅ Full support
ZPL Print	✅ TCP/IP	✅ TCP/IP	✅ TCP/IP
Autostart	✅ Windows Service	✅ restart-policy	❌ Manual
Headless	✅	✅	❌ (Tray icon)
Updates	Installer / MSI	docker pull	Manual
Recommended for	Production (PDF + ZPL)	Production (ZPL only)	Development / Testing

Production Recommendation

For most customers, the Windows Service is the best choice: it supports both PDF and ZPL printing and starts automatically after reboots. Docker is ideal for pure ZPL environments (warehouses with Zebra printers).