Salta ai contenuti
IT
Apri l’app

For AI assistants: this page as plain markdown is at https://docs.voicelogica.ai/raw/telephony/edge-device.md, and https://docs.voicelogica.ai/llms.txt lists the docs by topic, one file each, small enough to read whole. Read those rather than this HTML page.

Edge device

23 min di lettura
Copia come Markdown
Visualizza come MarkdownApri il file .md.md

Questi contenuti non sono ancora disponibili nella tua lingua.

An edge device is a small connector you install inside the customer’s network. It lets Voice Logica reach a phone system (PBX) that has no public address - an on-premise PBX at 192.168.x.x, 10.x.x.x or 172.16-31.x.x.

It only makes outbound connections. Nobody opens a port, forwards anything, or gives the PBX a public IP.

The PBX or carrier is…What to use
On the office LAN, private IP onlyEdge device (this page), then a Local IP PBX trunk
Reachable from the internet (public IP or hostname)Your own carrier - Public IP PBX
A SIP carrier (Yuboto, Telnyx, Twilio…)Your own carrier - VOIP provider
Registers to us (the PBX dials out)Your own carrier - Incoming PBX

If you type a private address into a Public IP PBX trunk, the drawer blocks it and offers switch to Local IP PBX. That is the signal you need a device.

  1. The device keeps a control connection to calls.voicelogica.ai over TCP 443 (secure WebSocket).
  2. It brings up WireGuard tunnels to the three Voice Logica media servers over UDP 51820. SIP and call audio travel inside those tunnels, and calls are spread across the three servers.
  3. On the LAN side it talks to the PBX like any other SIP phone or trunk.

Both connections start from inside the network. The device cannot be reached from the internet, cannot run arbitrary commands, and cannot reach the rest of your network.

Send this list to whoever runs the site firewall before install day.

  1. An always-on machine on the same network as the PBX: a Windows PC, a Linux box, a Raspberry Pi, a spare PC started from a USB stick, or a virtual machine. Not a laptop that sleeps or leaves the office.
  2. Outbound TCP 443 to calls.voicelogica.ai. The name must resolve - DNS filtering that blocks our domain stops enrollment.
  3. Outbound UDP 51820 to all three Voice Logica media servers: 65.21.125.239, 65.109.51.21 and 213.133.102.213. Without it the device shows online, and calls have no audio. With only the first address allowed, calls still work, relayed through that one server, so every call depends on it.
  4. All UDP both ways between the device and the PBX. A rule for port 5060 alone is not enough - audio uses changing ports. If the firewall needs exact ports, allow the PBX’s SIP port (usually 5060) and UDP 10000-46000 to the device.
  5. No inbound ports, no port forwarding, no public IP.
FromToPortsFor
Devicecalls.voicelogica.aiTCP 443Control connection
Device65.21.125.239, 65.109.51.21 and 213.133.102.213UDP 51820Call tunnels, one per media server
PBXDevice (on the LAN)SIP port, UDP 10000-46000Signalling and call audio

Call audio reaches the device on a fixed block of ports per media server: 40000-46000, 30000-36000 and 20000-26000. The rest of 10000-46000 is kept for a fourth server (10000-16000) and for router audio ports (10000-10020), so one rule for the whole range does not need changing later.

Full network sheet for IT: network requirements.

Start from what is already in the office, next to the PBX:

You have…Use
A Windows PC that stays onWindows
A Linux machine with DockerLinux
A spare PC or mini-PC with no operating system, or one whose disk may be erasedPC (install on disk)
A spare PC whose disk must stay as it isPC (USB stick)
A Raspberry Pi 4 or 5Raspberry Pi
A server that runs VirtualBox, VMware or ProxmoxVirtual machine

A spare PC needs no Windows or Linux. The installer stick erases the PC’s disk and puts the connector on it, so the PC then runs without the stick. If the disk must not be touched, the PC can run the connector from a USB stick instead, with the stick left in.

You can start from two places. Both produce the same device:

  • Telephony - Trunks - + Add Trunk - Local IP PBX. The drawer shows Download the connector with Windows, Linux, Raspberry Pi, PC (USB stick) and VM image, then waits for the device. Use this when you are connecting a PBX right now.
  • PBX Edge Devices (app.voicelogica.ai/phones/edge-devices) - Add Edge Device. Use this to prepare a device ahead of time, or to Email the steps to the customer when someone else is on site.

In Add Edge Device, give it a Site label (the office name, for example “HQ Office”), then answer two questions:

  1. Where will the edge device run? On a computer that is already in use, On a spare PC or On a Raspberry Pi.
  2. For a computer in use, What does that computer run? Windows, Linux with Docker or A virtualization server. For a spare PC, What should happen to the PC’s disk? Install on its disk (erases it) or Run from a USB stick.

Your answer shows at the top with Change to go back. Then choose I’ll set it up now or Email the steps to the customer. The main button changes to match.

  1. Choose On a computer that is already in use - Windows and click Download installer. The .exe is built for your company - the token is inside, nothing to type.
  2. Copy it to the always-on Windows PC next to the PBX. Run it and accept the prompts.
  3. It installs WireGuard and the connector as a service and connects by itself. It starts again after a reboot.

The download link is valid for 4 hours. After that, download a fresh one (Redownload Windows in the trunk drawer).

If antivirus or a browser policy blocks the .exe, run the PowerShell one-liner instead in an Administrator PowerShell:

Terminal window
$env:EDGE_TOKEN='<token>'; irm https://calls.voicelogica.ai/install.ps1 | iex

Claude or ChatGPT hands you this line with the token already filled in - see Or let Claude do it.

The token ties the device to your company. The first device of a company on a network is approved automatically. A second one shows Pending until a company admin approves it: on PBX Edge Devices, click Approve device (the check mark) on its row. It connects within a minute. A virtual machine is approved when you claim it with its code. Watch it on PBX Edge Devices (the list refreshes on its own) or in the trunk drawer:

State
Pending - just enrolled. Approved / Active - ready to use. Revoked - cannot be used; install a new one.
Online
Online once the device holds its control connection.
PBX
The PBX address the device is set to use, or Not set.

In the trunk drawer the pill changes from Not connected to Live, and Next steps appears. Refresh devices checks now.

  1. Telephony - Trunks - + Add Trunk - Local IP PBX

    Name the trunk after the site. If the device is already Live, the form unlocks right away.

  2. Pick the PBX

    Under Suggested PBXs on this LAN, click Find PBXs. The device scans its subnets for SIP hosts. Click a suggestion, or type the PBX’s LAN IP yourself.

  3. Set the SIP port if it is not 5060

    Advanced - Port. Some PBXs listen elsewhere - Alcatel OXO commonly uses 5059. Ask the PBX admin if unsure.

  4. Test now

    Sends SIP OPTIONS to the PBX through the device. Any answer - including 401/407 (wants credentials) - means SIP is flowing. No SIP response means wrong IP or port, or something between the device and the PBX drops SIP.

  5. Credentials

    The extension (or SIP trunk account) the PBX created for Voice Logica: Username, Password, and Login (Authorization ID) if the PBX uses a separate one.

  6. Destination, then Create Trunk

    Point unrouted calls at your AI agent. Create Trunk. Registration should show online within a minute.

  7. Send calls to the agent and dial in

    Route a number or a PBX queue / extension to the new trunk on the PBX side, connect it to the agent under Channels - Telephony, and call it from a real phone. Check Calls. See Your own carrier for numbers and default destination.

To change the PBX address on an existing device later, use the slider icon (Configure PBX settings) on its row in PBX Edge Devices - PBX IP address and SIP port, then Save. Pushing new settings restarts the device’s SIP relay, so do it outside a live call.

Some routers let call audio back in only on a fixed range of UDP ports that is forwarded to one computer. This is common when a carrier line runs over the carrier’s own router (for example Vodafone). Calls then ring and connect, but nobody hears anything: the device sends audio out, and nothing comes back.

The fix is to tell the device which ports the router forwards, so it uses exactly those for call audio.

  1. Forward the ports on the router. In the router’s settings (usually Firewall → Port Forward), forward UDP 10000-10020 to the computer running the device (its LAN address, e.g. 192.168.1.3). If the router already forwards a range to that computer, use that range instead.
  2. Set the same range. Telephony → Trunks → open the trunk → Router audio ports → type 10000-10020 → Apply. Or ask Claude: “set the edge device audio ports to 10000-10020”.
  3. Close other phone apps on that computer (softphones such as MicroSIP). Two programs cannot use the same ports.
  4. Make a test call. Both sides should hear each other right away.

Each call uses two ports, so 10000-10020 carries 10 calls at the same time. To go back to the device’s own ports, clear the field and press Apply. The setting belongs to the device: every trunk on it uses it. It needs device version 1.1.39 or newer, which installs itself.

Prefer help? If you connected Claude or ChatGPT, say “my calls have no audio”. It reads the device’s audio counters, tells you what to forward and sets the ports for you.

Pausing takes a device out of service without uninstalling it. While it is paused, Voice Logica passes none of its calls: no line registers through it and no call goes in or out through it. The machine stays installed and online, and resuming switches it straight back. Use it to test with only one device, or to take an old device out before you uninstall it.

There is no button for it in the app yet. If you have connected Claude or ChatGPT:

  • Pause: say “pause the edge device on the old PC” (or name its site). It lists the devices and pauses the one you mean.
  • Resume: say “resume the edge device on the old PC”. A line through it registers again within a few minutes.
  • Check: “show my edge devices” shows a paused device as paused, with who paused it and when.

A call that is already connected keeps its audio until it ends. A line that goes only through the paused device stops working until you resume it, so pause at a quiet time or only a device whose lines have another way in.

Two devices with the same line. A line always goes through the device its trunk is set up on. If an old device still has the same line configured, calls can ring on the wrong phones or have no audio: pause the old device (or uninstall it) so the phone system is reached through one device only.

If you have connected Claude or ChatGPT to Voice Logica, say “connect my PBX”. The assistant gives you the Windows download link (or the Linux command) with the token inside, watches the device come online, asks for the PBX IP, SIP port and extension login, and creates the trunk through the device. Walkthrough: Connect your PBX from Claude.

For a Raspberry Pi, put the microSD card in your computer and say “I want a Raspberry Pi edge device”: the assistant prepares the card, or tells you how, as described under Raspberry Pi.

Why do calls have no audio when my edge device shows online?

The tunnel is down. The site firewall must allow outbound UDP 51820 to the three media servers (65.21.125.239, 65.109.51.21 and 213.133.102.213). The trunk drawer says Connected, but the tunnel is down (UDP 51820); Claude reports tunnelUp: false.

If the tunnel is up and audio is still silent both ways:

  1. The firewall between the device and the PBX passes all UDP, not only 5060. If it lists ports, it must include UDP 10000-46000 to the device: a rule for 40000-46000 alone drops the calls that run on the second and third media server.
  2. On Linux, a default-deny host firewall drops audio. Run ufw allow in on wg0 on the device.
Why does the agent speak but never hear the caller on calls through my edge device?

The tunnel is fine and the call is up, but no audio comes back from the carrier or PBX. The device reports it: Telephony → Edge devices shows a No call audio warning with the likely cause, and Claude sees toServer: 0 in the device media.

  1. The router forwards only a fixed UDP range to this computer: set Router audio ports.
  2. SIP ALG is off on the router, if you can reach that setting.
  3. No other phone app on the same computer is registered with the same number.
Why does my edge device never come online?
  1. The installer finished and the machine is on (not asleep).
  2. Outbound TCP 443 to calls.voicelogica.ai is allowed.
  3. The name resolves - DNS / web filtering often blocks new domains. Allowlist calls.voicelogica.ai and voicelogica.ai.
  4. The Windows link (4 hours) or install token (72 hours) had not expired. If in doubt, generate a new one.
Why does Test now on my edge device say No SIP response?

The PBX’s IP or port is wrong, or the PBX ignores the edge device. Confirm the PBX’s SIP port - it is not always 5060 (Alcatel OXO: 5059) - and set it under Advanced - Port. A 403 Forbidden means SIP arrives but the PBX rejects this source: allow the device’s LAN address in the PBX’s SIP / trunk settings.

Why does Claude say my PBX is not reachable when the edge device test works?

PBX reachable is a ping from the edge device. Many networks and PBXs block ping while SIP works fine. Trust Test now and the trunk’s registration, not the ping.

balenaEtcher stops with 'The writer process ended unexpectedly'. What now?

The image itself is fine; the write fails on the computer preparing the stick.

  1. Use a stick of 8 GB or more. The image unpacks to 6.5 GB, and some cheap “8 GB” sticks are slightly smaller: try another stick.
  2. Close Etcher, right-click it - Run as administrator and accept the Windows prompt. Antivirus or Controlled folder access can also block the write: allow Etcher, or pause it while flashing.
  3. Still failing: unzip the file first with 7-Zip (right-click - 7-Zip - Extract here) to get voicelogica-edge-pc.img, and write that with Rufus: pick the stick, SELECT the .img file, START, and choose DD Image mode if Rufus asks.
  4. Then copy voicelogica.txt to the VLSETUP drive as usual.
Why does the PC not start from the USB stick?
  1. Press the boot menu key right after power-on: F12 on Dell and Lenovo, F11 on MSI, Esc or F9 on HP. Pick the entry with the stick’s name or USB.
  2. The stick does not appear in the list: in the BIOS, turn on USB boot, and turn off Secure Boot if the PC refuses the stick.
  3. It starts, but the device never shows up: check the network cable, and that voicelogica.txt is on the VLSETUP drive. Without the file, read the Claim code on the PC’s screen and claim it.
Why does my Raspberry Pi not show up?
  1. Look at the lights. A steady red light and a green light that never flickers mean the Pi is not reading the card. Push the card fully into the slot under the board (contacts facing the board). A Pi 1, Pi 2 or the original Pi Zero cannot run the image: use a Pi 4 or 5.
  2. Check the cable. The Pi needs a network cable to a LAN port of the router or switch, not the WAN/Internet port. Wi-Fi is not used. The socket’s lights come on when the cable is connected.
  3. Wait 5 minutes. On the first start the Pi downloads the Voice Logica agent, and on a slow line that takes a few minutes. It keeps retrying until the network is there.
  4. Check the card. Put the card back in your computer. If voicelogica.txt is still on the bootfs drive, the Pi never started from the card: write it again, or try another card. If the file is gone, the Pi started and read it, so the network is the problem: the site must allow outbound TCP 443 to calls.voicelogica.ai.
  5. It shows Pending: approve it, as described under Wait until it is online.
Can one edge device serve two PBXs on different networks?

No. One edge device serves one PBX target at a time. Install a second device next to the second PBX, then create a second Local IP PBX trunk through it.

Why do callers reach nothing when my trunk through the edge device is registered?

Either the PBX is not sending those calls to the trunk, or the number is not on this agent. Check the routing on the PBX first, then the trunk’s default destination and the agent’s Channels - Telephony, as described in Your own carrier.