Field runbook

The on-site procedure for installing a connector, from delivery to a verified test print. Five steps, and a troubleshooting matrix at the end. The page is printable.

Prerequisites

• The connector. It arrives assembled and ready to power on; configuring it is steps 2 to 4 of this procedure.
• A laptop or phone that can join the venue's network.
• Network access for the connector, on the same LAN as the devices it will drive.

Replacing a unit that has died

A reassignment token is only needed when you are replacing hardware, not when you are installing it for the first time. It hands a replacement unit everything the dead one was running, so every device, assignment and setting comes back untouched and no integration has to change.

A unit belongs to whoever set it up first, and that is who replaces it. If other integrators were also using the unit, their connectors come across in the same step and they do nothing at all. If a connector of yours is running on somebody else's unit, its page names them and how to reach them; replacing that hardware is their call, not yours.

The procedure, in order:

1. Issue the token from the dashboard (Access → Replacement), picking any connector of yours that was running on the unit that died; that is how you point at the unit. Do this on arrival rather than in advance: two hours is shorter than many site visits.
2. Fit the replacement unit and connect it to the same network.
3. Open the replacement's setup page (http://raven-connector.local:7070) and type the token where it asks for one, instead of scanning the code it is showing.

Three things will refuse the swap, each for a reason worth knowing before you travel. The old unit must have stopped reporting: Raven will not take connectors off hardware that is still working. The replacement must be carrying nothing, so it cannot be a unit already in service elsewhere. And the replacement must have room for everything being moved.

A token is consumed only when a unit actually takes the swap. A refusal leaves it spendable, so the three above are worth reading and retrying rather than phoning for a new token. Nothing is ever half-moved: either every connector comes across or none does.

1. Install and connect

Connect power, then network. Ethernet is preferred where a port is available. The connector must be on the same LAN and subnet as the printers, scales and other devices it will reach. A guest SSID is isolated from the LAN and will not work.

2. Enroll the connector

The connector advertises itself on the LAN as raven-connector.local and serves a setup page on port 7070. Its IP address is not needed. From any machine on the same network, open:

Open raven-connector.local:7070 http://raven-connector.local:7070

This address resolves only on the venue's own network, from a device that supports mDNS. Elsewhere the link will fail to connect.

The page shows a code as soon as it opens. Scan it with a phone, or tap the code itself on the device you are already reading it from; either way it opens the Raven dashboard in a new tab, where the integrator signs in and approves. The setup page keeps counting down and watching for the approval in the tab you left it in. Nothing is typed into the connector and no token is carried to the venue. If a code is already on screen from an earlier attempt, or the page offers a Show the code button instead, reload and use whatever the page shows you then.

The approval screen asks the integrator for two things: a name for the connector, and the last four characters of the unit's serial. The setup page prints those four characters on their own, above the full serial, so read them off the page you have open in front of you and give them to whoever is approving. The approval screen deliberately does not show them.

Never take those characters from a link, a photo or a message. Reaching the setup page means being on the venue network with the unit; being sent the characters means nothing about the hardware they belong to. An approval granted on characters somebody supplied binds your connector to whichever box that person is holding. If you are approving remotely, get them from the person standing at the unit by a route you already trust, and treat an unsolicited enrollment link as something to refuse.

Name the connector after the venue. This name identifies the site in every list, alert and support record, and is not practical to change afterwards. See Connector settings.

The code is valid for fifteen minutes and can be used once. The page counts the time down as you work. If it runs out, reload the page and start again; the previous code stops working the moment a new one is issued, so only ever scan the code currently on screen.

If the setup page is unreachable

• .local resolution requires mDNS. It is supported by macOS, iOS, current Windows and Android, and is commonly blocked on corporate laptops and guest networks. If the name does not resolve, take the connector's address from the router's integrator list and use http://<address>:7070.
• Confirm the machine is on the LAN, not a guest SSID.
• The page stays available for the life of the unit, enrolled or not. It is how a second integrator is added later and how support identifies the unit, so its absence is a fault rather than an expected state.
• If the page shows an activation form instead of the enrollment button, the unit was shipped without being registered. Contact Raven; it cannot be enrolled until it is.
• If the QR code does not appear after pressing the button, the page states why. "Too many attempts" clears on its own within seconds. Anything naming Raven is not a site fault; quote the serial shown on the page.

3. Discover hardware

The connector now appears in the dashboard. Open it and run Discover. The connector scans the LAN and its local ports and lists what it finds. Printers and scales that identify themselves are listed automatically. Hardware that cannot be identified, such as a generic HTTP device or a serial node, is added manually with its address and a name.

4. Create and assign devices

Create one logical device for each device the customer's software will address, then assign the discovered hardware to it. The logical device holds the id the integration stores, so replacing hardware later is a reassignment rather than a code change.

Set paper width and character set at this point; both affect output and are easier to verify with the printer in front of you. See Printer settings.

5. Verify

Run Test print on each printer and confirm the output physically. A job may report as delivered on a printer that is out of paper, so the dashboard status alone is not sufficient evidence.

Before leaving the site, confirm on the connector's page that:

• the connector is online;
• every device is assigned and reporting;
• each test print was produced.

Troubleshooting

Integration against a live venue is covered in Quickstart.