diff --git a/public/images/manufacturers/astrolabs.webp b/public/images/manufacturers/astrolabs.webp new file mode 100755 index 0000000..bfd2b5a Binary files /dev/null and b/public/images/manufacturers/astrolabs.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/calibration.webp b/src/content/docs/focusers/astrolabs/scopelink/images/calibration.webp new file mode 100755 index 0000000..9116414 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/calibration.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/connection.webp b/src/content/docs/focusers/astrolabs/scopelink/images/connection.webp new file mode 100755 index 0000000..3ba7766 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/connection.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/diagnostics.webp b/src/content/docs/focusers/astrolabs/scopelink/images/diagnostics.webp new file mode 100755 index 0000000..e2a7aa2 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/diagnostics.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/fans.webp b/src/content/docs/focusers/astrolabs/scopelink/images/fans.webp new file mode 100755 index 0000000..af9fe16 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/fans.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/focuser.webp b/src/content/docs/focusers/astrolabs/scopelink/images/focuser.webp new file mode 100755 index 0000000..6589042 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/focuser.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/general-info.webp b/src/content/docs/focusers/astrolabs/scopelink/images/general-info.webp new file mode 100755 index 0000000..df68009 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/general-info.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/main-control.webp b/src/content/docs/focusers/astrolabs/scopelink/images/main-control.webp new file mode 100755 index 0000000..4de55b9 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/main-control.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/options.webp b/src/content/docs/focusers/astrolabs/scopelink/images/options.webp new file mode 100755 index 0000000..219b048 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/options.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/parameters.webp b/src/content/docs/focusers/astrolabs/scopelink/images/parameters.webp new file mode 100755 index 0000000..82c5404 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/parameters.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/power.webp b/src/content/docs/focusers/astrolabs/scopelink/images/power.webp new file mode 100755 index 0000000..ebb9bcb Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/power.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/images/telemetry.webp b/src/content/docs/focusers/astrolabs/scopelink/images/telemetry.webp new file mode 100755 index 0000000..9e3388d Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/images/telemetry.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/scopelink.md b/src/content/docs/focusers/astrolabs/scopelink/scopelink.md new file mode 100755 index 0000000..688399d --- /dev/null +++ b/src/content/docs/focusers/astrolabs/scopelink/scopelink.md @@ -0,0 +1,298 @@ +--- +title: ScopeLink +categories: ["focusers", "dustcaps", "lightboxes", "auxiliaries"] +description: Focuser, front flap, flat panel, fans and auxiliary power on the Astrolabs ScopeLink telescope controller. +thumbnail: ./scopelink.webp +--- + +# ScopeLink + +## Installation + +| | | +|---|---| +| **Driver name** | ScopeLink | +| **Executable** | `indi_scopelink` | +| **Author** | Bence Toth, Astrolabs Hungary Kft. | +| **Maintainer** | Bence Toth <bence.toth@astrolabs.hu> | +| **Version** | 1.0 | +| **Device type** | Focuser, dust cap, light box, auxiliary | +| **Connection** | Serial (USB CDC-ACM) | +| **Minimum INDI** | 2.0.0 | +| **Platforms** | Linux (amd64, arm64) | + +Install with `sudo apt install indi-scopelink`, or build it from source — the driver lives in +[indi-3rdparty](https://github.com/indilib/indi-3rdparty), and its `INSTALL.md` has the instructions. + +After installing, reload the udev rules so the controller is reachable without root privileges: + +```sh +sudo udevadm control --reload-rules && sudo udevadm trigger +``` + +## Overview + +ScopeLink is a single-box telescope controller from Astrolabs. One USB connection drives: + +- a stepper focuser +- a motorised front flap over the telescope aperture +- a flat panel +- two mirror cooling fans, thermostatically controlled against the mirror-to-ambient temperature + difference or switched by hand +- two auxiliary power outputs +- a powered USB hub with per-port fault reporting (generation 3) + +The driver publishes all of it as one INDI device. The interfaces it claims depend on what the connected +controller actually has, which is read out of the hardware at connect time. + +### Supported models + +| Generation | Focuser | Front flap | Aux power | USB hub | Smart switch diagnostics | +|---|---|---|---|---|---| +| 2 | yes | yes | yes | no | no | +| 3 | yes | yes | yes | yes | yes | + +**Generation 3 is the production hardware.** Generation 2 is the earlier controller; it runs the same +code path, differing only in what the capability read at connect time turns on. The driver is tested +against real units of both. + +The infrared temperature sensor is a fitting option rather than a generation difference. On a unit +without one, the temperature readings, the mirror ΔT and the automatic fan targets are not offered at +all, rather than being offered and failing. + +## Connecting + +Select **ScopeLink** in the Focuser slot of your Ekos equipment profile. Ekos picks up the dust cap and +light box interfaces from the same device automatically once it connects, so the front flap appears in +the cap controls and the flat panel in the flat frame settings — there is no need to add the device +twice. + +On the **Connection** tab, set the port. Prefer the per-unit name under `/dev/serial/by-id/` to +`/dev/ttyACMn`, which is renumbered whenever another CDC device is plugged in first: + +```sh +ls -l /dev/serial/by-id/ +# usb-STMicroelectronics_STM32_Virtual_ComPort_in_FS_Mode_205E35793630-if00 -> ../../ttyACM0 +``` + +The number in that name is the controller's USB serial, so it identifies one physical unit and a saved +profile keeps working across reboots and however many other USB devices are plugged in. Without the udev +rule installed you also have to be in the `dialout` group to open the port. + +> [!NOTE] +> ScopeLink currently reports ST's generic USB identifiers, `0483:5740`, which every STM32 device running +> the stock USB CDC stack also reports. The udev rule therefore grants access but deliberately creates no +> `/dev/scopelink` name, since it could not tell a ScopeLink from any other such device. A product +> identifier of our own has been requested from STMicroelectronics. + +The baud rate is offered because libindi's serial plugin expects one, but the controller is a CDC-ACM +device and ignores it. + +![The Connection tab, with the port set to a per-unit name](./images/connection.webp) + +Two options are worth setting before the first connection, on the **Options** tab: + +- **Step multiplier** — how many controller steps make one client step. Leave it at 1 unless the + focuser's travel is large enough that a client is unhappy with the numbers. It is applied when the + driver connects, so changing it while connected has no effect until you reconnect. +- **Controller diagnostics** — off by default. Turning it on adds the controller's own die temperature, + supply rail, CPU and stack load and I�C error counter to the Telemetry tab. These are for + fault-finding, not for observing. +- **Simulated hardware** — which generation the driver imitates while **Simulation** is on. Ignored + otherwise. See "Running without a controller" below. + +![The Options tab](./images/options.webp) + +On a successful connection the **General Info** tab shows the hardware and interface versions, the +unit's hardware identifier and the firmware string. Quote all four in any support request. + +![The General Info tab](./images/general-info.webp) + +### Running without a controller + +Turn **Simulation** on before connecting and the driver answers itself: no port is opened, and every tab +below behaves as it does on hardware, including motion, the flat panel, the fault store and the +configuration parameters. **Simulated hardware** on the Options tab picks which generation it imitates, +which is what makes the differences between them visible — the USB hub and the smart switch settings +appear and disappear as they would on the real controllers. + +It is meant for trying the driver out, for reproducing a problem without the hardware to hand, and for +client development. The simulated controller is answerable and self consistent; it is not a model of the +firmware, and the values it reports are plausible rather than measured. + +The same simulated controller is also available on a pseudo terminal, from the `scopelink-simulator` +command, for anything that needs a port rather than a driver. + +## Focuser + +Standard INDI focuser controls: absolute position, relative moves, abort, and sync. + +The travel limit is read from the controller's own calibration when the driver connects, and +`FOCUS_MAX` is deliberately read-only — writing it from the focus module would silently overwrite a +bench calibration. Recalibrating is what the Calibration tab is for. + +**Temperature** shows the ambient reading from the infrared sensor, and is what Ekos uses for +temperature-compensated focusing. If the sensor stops answering, the property goes to alert rather than +reporting the plausible-looking -273 °C the hardware sends in that case. + +If a move ends with the motor stopped somewhere other than the commanded position, the driver reports an +alert rather than a completed move. That normally means the focuser is obstructed or the motor's stall +detection sensitivity is set too high. + +![The Focuser tab during a move](./images/focuser.webp) + +## Front flap (dust cap) + +The flap is published as a dust cap, so Ekos opens and closes it as part of a sequence without being +asked each time. + +**Park** closes the flap, **Unpark** opens it. The raw motor position and the fraction of travel are +shown alongside, which is useful while calibrating. + +If the driver connects and finds the flap stopped somewhere between its end stops — after a power cut +mid-travel, for instance — it reports the state as unknown and **does not move it**. Close or open it +once to re-establish where it is. + +![The Main Control tab, with the front flap opening and the flat panel below it](./images/main-control.webp) + +## Flat panel (light box) + +**Flat panel** switches the panel on and off; **Brightness** sets the duty cycle from 0 to 100 %. Ekos +drives both automatically when taking flat frames: a flat job closes the cover, turns the panel on, takes +its frames and turns it off again, without being asked. + +The brightness you set while the panel is off is remembered and applied when you switch it on. Switching +the panel on with the brightness at zero produces no light, and the driver says so in the log. + +## Telemetry + +Read-only. Supply, rear fan and side fan rail voltages; ambient and mirror temperature and the +difference between them; and the load on each motor. + +With **Controller diagnostics** enabled in Options, a second group appears with the infrared sensor +supply, the controller's own supply and die temperature, CPU and peak CPU load, stack usage and the I�C +error counter. + +![The Telemetry tab with controller diagnostics enabled](./images/telemetry.webp) + +## Fans + +Each fan can be left under the controller's own thermostat or taken over manually. + +- **Manual control** — enables the override for each fan independently. +- **Commanded state** — what each fan does while its override is enabled. +- **Automatic targets** — the mirror-to-ambient temperature difference each fan aims at when it is not + overridden, in Kelvin. Only offered on a unit with the temperature sensor fitted, since there is + nothing to regulate against without it. + +![The Fans tab](./images/fans.webp) + +## Power + +**Auxiliary outputs** switches the two auxiliary power outputs. + +**USB hub** reports the downstream ports (generation 3): whether each is powered, and whether it has +tripped. A port fault lights red and is also recorded in the fault store. + +![The Power tab on a generation 3 unit](./images/power.webp) + +## Parameters + +Every configuration value the connected controller holds, grouped by subsystem: focuser motor, flap +motor, fans, temperature, smart switch monitoring. Values are read when the driver connects. + +Only the values you actually change are written. This matters: they live in EEPROM, which has a finite +number of write cycles, and the wear counters on the Diagnostics tab exist because of it. After a write +the driver reads the value back, so anything the controller clamped or refused is visible immediately. + +- **Reload from controller** — read every value again. +- **Export to file** — write the whole configuration to the path in **Parameter file**. `~/` is + expanded. +- **Import from file** — read that file and write any values that differ to the controller. + +The file format is the one the vendor's Windows parameter editor reads and writes, so configurations +move between the two platforms. A file exported from a generation 3 unit can be imported on a +generation 2 one; values that generation does not hold are skipped. + +![The Parameters tab](./images/parameters.webp) + +**Take an export before changing anything.** It is the only backup of a unit's calibration. + +## Diagnostics + +**Faults** shows how many diagnostic trouble codes are stored and how many are active right now. + +- **Read fault store** — lists the stored codes with, for each, whether it is currently active, how many + times it has been seen and when it was first recorded. The full freeze frame — around thirty values + captured at the moment the fault was raised — is written to the driver log, where it can be copied + into a support request. +- **Clear fault store** — clears every stored code and reads the store back. A code whose cause is still + present reappears immediately, which is the point of reading it back. +- **Read EEPROM counters** — the wear counters for the controller's configuration memory. + +**Link health** shows the transaction, retry and failure counts for the serial link, and how old the +most recent status sample is. Retries are normal on a busy USB bus; a rising failure count is not. + +![The Diagnostics tab, showing one stored fault and the EEPROM wear counters](./images/diagnostics.webp) + +## Calibration + +Establishes a motor's travel, for the focuser or the front flap. The procedure is the same for both: + +1. Select the motor. +2. If the travel is unknown or wrong, press **Reset calibration**. The motor is then free to move + anywhere, and believes it is in the middle of an unbounded travel. +3. Jog the motor to one end stop, using **Jog towards zero** and **Jog away from zero** with a jog size + that gets smaller as you approach. Watch the motor load while you do — a rising load means you have + reached the stop. +4. Press **Mark as zero**. +5. Jog to the other end stop. +6. Press **Mark as end of travel**. + +**Stop** halts the selected motor immediately. + +The travel readouts update as you go, and the driver picks up the new limit without a reconnect. + +![The Calibration tab](./images/calibration.webp) + +> **Take care with the front flap.** Once it is calibrated, Ekos will drive it automatically. A flap +> whose travel is set wrong will be driven into its end stop on every sequence. + +## Troubleshooting + +**The port cannot be opened.** Reload the udev rules with +`sudo udevadm control --reload-rules && sudo udevadm trigger` and unplug and replug the controller. +Failing that, add your user to the `dialout` group and log out and back in. + +**The port keeps changing number.** `/dev/ttyACMn` is handed out in the order devices are plugged in. +Point the profile at the `/dev/serial/by-id/` name instead, as described under Connecting; it stays with +the unit. + +**"No ScopeLink answered on …".** Something is on the port but it is not answering as a ScopeLink. Check +you have the right port — `scopelink-cli --port /dev/ttyACM0 info` is a quicker way to test than a full +client — and that nothing else has the port open. The driver refuses the connection rather than +half-connecting to an unknown device. + +**"hardware generation N is not supported".** The controller is newer than the driver. Update the +driver. + +**The driver disconnects itself during a session.** Three failed status polls in a row are treated as a +lost controller, after the protocol layer has already retried each one three times. Check the USB cable +and the supply voltage on the Telemetry tab; a supply sagging under load is the usual cause. The Link +health readout on the Diagnostics tab shows whether the link was struggling beforehand. + +**No temperature readings.** Either the unit has no infrared sensor fitted — in which case the +properties are not offered at all — or the sensor has stopped answering, in which case they go to alert +and a fault is stored. Read the fault store to tell the two apart. + +**The flap state is reported as unknown.** It stopped between its end stops, most likely because power +was lost mid-travel. Close or open it once to re-establish where it is. + +## Reporting problems + +Include: + +- the four values from the **General Info** tab +- the driver log with **Debug** enabled, covering the problem +- the freeze frames from **Read fault store** +- an export of the parameters diff --git a/src/content/docs/focusers/astrolabs/scopelink/scopelink.webp b/src/content/docs/focusers/astrolabs/scopelink/scopelink.webp new file mode 100755 index 0000000..1b69e69 Binary files /dev/null and b/src/content/docs/focusers/astrolabs/scopelink/scopelink.webp differ diff --git a/src/content/docs/focusers/astrolabs/scopelink/scopelink.yaml b/src/content/docs/focusers/astrolabs/scopelink/scopelink.yaml new file mode 100755 index 0000000..6e041f8 --- /dev/null +++ b/src/content/docs/focusers/astrolabs/scopelink/scopelink.yaml @@ -0,0 +1,17 @@ +# Display Names (Human-Friendly - Required) +driver_name: ScopeLink +manufacturer_name: Astrolabs + +# Categories (Required - can be multiple) +categories: + - focusers + - dustcaps + - lightboxes + - auxiliaries + +# Additional Metadata (Optional) +website: www.astrolabs.hu +executable: indi_scopelink +platforms: Linux +author: Bence Toth +version: 1.0