The INDI driver: the control panel

Where the wheel is

Wheelly WHEELLY_POSITION · read-only

Where the wheel really is, as read by the magnetic sensor, refreshed at every poll (every POLLING_PERIOD, 250 ms by default). Look at it while centring a slot, or when a filter change ended with a warning or a failure: it tells how far off the wheel stopped and how many retries it took.

• Read-only. Display limits: angle 0-360, error -180 to +180, retries 0-99.
• The verdict (arrived, warning, failed) is given by the firmware, not by this property: see FILTER_SLOT and the log.
• If the wheel moves on its own while at rest beyond the Alert tolerance, the log says so once per episode and suggests the holding current at rest (WHEELLY_HOLD), or, if it is already on, looking at the clutch spring preload.

Magnetic sensor

Wheelly WHEELLY_SENSOR · read-only

The state of the AS5600 magnetic sensor, refreshed at every poll. It is instrumentation to keep an eye on: a sensor wire working loose, or the power jumper of the sensor module lifting, shows here before it shows in a bad frame. The property turns red (Alert) when the magnet is not detected.

• Read-only.
• If the sensor does not answer at all, AGC and Magnitude read 0 and MD reads 0.
• When the magnet disappears the log shows an error: 'The sensor no longer detects the magnet. This is serious: check the sensor wiring before imaging further.' Once per episode: if the magnet comes back and is lost again, it is said again.
• For a full check of the sensor and of the motor driver use 'Hardware check' (WHEELLY_DIAG).

Wheel configuration

Wheelly WHEELLY_CONFIG

'Save to the wheel', here too: it writes to the wheel's permanent memory everything the wheel holds, as the button of the same name in the Calibration and Diagnostics tab (WHEELLY_SAVE) does. It sits right under Configuration so that the settings of this tab that live in the wheel - motor, holding current, direction, LED - are saved without leaving it.

• Configuration above it is INDI's own and saves the settings of this computer and profile, not the wheel's: the two do not replace each other. A separate row and not a fifth button in Configuration: Ekos counts on its four, and KStars would show five as a drop-down menu.
• Always shown, like Configuration; pressed with the wheel disconnected it goes to Alert and the log says 'Connect the wheel first.'

Firmware

Wheelly WHEELLY_FIRMWARE · read-only

What the wheel said about itself when the driver connected: firmware version, protocol version and serial number. Useful when reporting a problem, and to know which wheel this profile is bound to.

• Read-only.
• Saved in the INDI configuration: the saved serial number is what the profile looks for at the next connection (see CONNECTION).
• A firmware with another protocol version is refused at connection, with a log message saying which side to update.

Motor

Wheelly WHEELLY_MOTOR

The settings of the stepper motor while it turns the wheel. The run current is the one to tune: raise it until the friction drive stops slipping, and no further, since more current means more heat.

• Limits in the panel: run current 1 to 800 mA (step 5), speed 1 to 5000 (step 10), acceleration 1 to 50000 (step 50).
• The default of 350 mA was measured on the reference wheel, where the clutch stops slipping; the motor is rated 400 mA per phase. With its detent still in place the wheel needed 400 mA to climb out of a notch; with the detent removed, as the assembly guide always does, 350 mA arrived at every speed from 100 to 1000 steps/s.
• Set sends the three values to the wheel together; the fields then show what the wheel accepted.
• Lowering the run current below the holding current also lowers the holding current in the wheel.
• Speed and acceleration are in full motor steps: 200 steps/s is one motor turn per second, about 124 degrees of disc per second on Wheelly (the clutch turns the disc 2.9 times slower than the motor); the default 300 steps/s is about 186 degrees per second.
• Slower is not gentler: this motor has little torque below about 250 steps/s (75 rpm, where its datasheet curve starts), and at 50 steps/s it stalled and vibrated at some notches of the reference wheel's detent (now removed) even in the easy direction, while from 100 up to 1000 every move arrived. The default is 300/1200. After a leg that stalls anyway, the wheel runs the next one at twice the speed and acceleration (at most 1000 steps/s) to break out of the notch.
• The wheel's time cap on a move follows the speed: if with the new values the longest possible filter change would go past the 30 s after which Ekos gives up, the log warns ('With these motor settings the longest filter change can take up to N s ...').
• Kept by the wheel until switched off; press 'Save to the wheel' to keep it. Not stored in the INDI configuration.
• Alert if the wheel refused the value; the reason is in the log.

Holding current at rest

Wheelly WHEELLY_HOLD

Whether the motor stays powered when the wheel is at rest. The default is 0: at the end of each move the motor is released, with no current, no heat next to the camera and no chopper noise during exposures. The wheel's detent is always removed (the motor cannot climb out of its notches), so what keeps the disc still at rest is the clutch pressing on it; if the wheel drifts at rest anyway - the log says so - set a reduced holding current so the disc cannot turn on its own. The second field is how long the stopped motor keeps holding the disc, at the run current, after every move before it is released - also when the holding current at rest is 0.

• The light says it too: green while the holding current is on, grey when the motor is released (0), whether it was set from the panel or read at connection.
• Where to start, if the wheel drifts: 150 mA, the value this project suggests. The log says it too, in the message that reports the drift. The field shows what the wheel holds, 0 included, and not 150 as a suggestion: a wheel saved at 0 would seem to have gone back to 150.
• Limits in the panel: 0 to 800 mA, step 5. The wheel refuses a holding current above the run current (log explains, property goes to Alert).
• Setting a value above 0 writes a warning to the log: the motor warms up next to the sensor and the driver sings during exposures.
• 150 mA and not the run current because holding lasts all night: about 1.35 W instead of 7.4 W.
• Why the hold after arrival: the motor drives the disc by friction, and a stopped motor that is still powered holds the tyre, which brakes the disc; released at once, the disc could coast on. The wheel reads its verdict at the end of the hold, so a disc that went on moving is judged where it stopped and corrected like any other miss. A heavier disc or a softer tyre may want longer; 0 reads before the disc has settled and costs extra legs.
• Limits for the hold after arrival: 0 to 2000 ms, step 50. It lengthens every leg, so the wheel's time cap on a move grows with it (the log warns if it goes past Ekos's 30 s, see WHEELLY_DIRECTION). It is read back from the wheel at connection; an older firmware does not have it, keeps its fixed 300 ms, and a change of this field goes to Alert.
• Kept by the wheel until switched off; press 'Save to the wheel' to keep it. Not stored in the INDI configuration.

Direction of travel

Wheelly WHEELLY_DIRECTION

Which way the wheel may turn to reach a slot. A mechanism that is stiffer one way than the other - as a wheel with an asymmetric detent is, a gentle flank one way and a steep one the other - can stall the stiff way: the motor hums and vibrates and the disc does not move. Turning one way only avoids it. The switch shows the value read back from the wheel.

• One way, every move and every retry go that way: after an overshoot the wheel goes round the whole turn instead of backing up the stiff way. So that it does not overshoot, each leg stops a little short of the target and the next ones creep in: a move takes a few legs, and these approach legs are not retries. Whether it arrived is still judged by the angle read.
• One way, a move can be almost a whole turn, and one retry another turn: the wheel's time cap on a move grows with it. If the longest possible filter change would go past the 30 s after which Ekos gives up, the log warns ('With these motor settings the longest filter change can take up to N s ...') - when the direction or the motor speed is set, and at connection. Raise the speed, or choose the shortest way if the wheel allows it.
• Kept by the wheel until switched off; press 'Save to the wheel' to keep it. Not stored in the INDI configuration.
• Grey (Idle) only with a firmware that does not know the setting; Alert if the wheel refused the command.

LED

Wheelly WHEELLY_LED

What the LED on the wheel does. The LED sits inside the light path, so the default keeps it dark while all is well: it breathes gently while the wheel goes to another filter, and blinks a signal of its own when something is wrong - the table below says which. The switch shows the mode read back from the wheel.

• A new mode is kept by the wheel only until it is switched off; the log reminds you to press 'Save to the wheel' to keep it.
• Do the test with the cover open or in daylight: the LED is inside the optical path. The log says so when the test starts.
• During the test the switch already shows the mode in use again; the blinking goes on for its 6.7 s.
• The alarm signals in the table show one at a time, the gravest first (magnet, then slot not reached, then drift), at the brightness of the top of the pulse. In 'Off' there are none: that is also the mode to turn the wheel by hand with the motor unpowered, which would otherwise read as a drift.
• Alert if the wheel refused the command.

Number of slots

Wheelly WHEELLY_SLOTS

How many filter positions the wheel has. The number lives in the wheel, and the driver reads it at every connection: set it here once, when the wheel is built. Changing it restarts the calibration from evenly spaced angles and generic filter names, and the panel is redrawn at once with the new number of positions, names and angles, and the slot-pitch jog buttons follow (360 divided by the number).

• After changing it: teach each position (the steps, then Set on its row of the angles), name the filters, then press 'Save to the wheel'. The log says so.
• Nothing is written in the wheel's permanent memory until 'Save to the wheel': switching the wheel off brings back the previous number and calibration, so a wrong click costs nothing.
• Refused while the wheel is moving; the reason is in the log.

▶ 1

Wheelly WHEELLY_ANGLE_1

The calibration angles, one row per slot, each with its own Set: this is slot 1's, and the rows of the other slots work the same. The number is the taught angle, in degrees, where that filter sits in the light path and where the wheel goes for it, as stored in the wheel. The slot the wheel is on is marked with an arrow, '▶ 1'. CALIBRATING A SLOT: choose it in FILTER_SLOT; centre the filter with the steps (WHEELLY_JOG_DOWN and WHEELLY_JOG_UP) - after every step its row shows the angle the wheel is at now, with an asterisk, '▶ 1 *', which means not taught yet; press Set on that row to teach it; do the same for every slot, then press 'Save to the wheel'.

• The asterisk, '▶ 1 *': the row shows where the wheel is after the steps, NOT what the slot has learnt. Set with the value as it is confirms it: the slot takes that angle and the wheel does not move, it is already there (log: 'Slot 1 now means the angle the wheel is at right now ...'). Leave the slot without pressing Set - choose another filter, run the sweep, or press Set on another row - and the row goes back to the taught angle, without the asterisk: the steps taught nothing.
• Set on a row with a different value - typed in, on any row, the starred one included: the slot takes the new angle and the wheel goes there at once, as if the slot had been chosen in FILTER_SLOT, which goes Busy and then Ok or Alert. That is how a filter is centred by numbers, and how the calibration is corrected while watching a star or a flat. Set on a row with its value unchanged only takes the wheel to that slot.
• Every change is written in the log - 'Slot 2: 122.87° → 123.10°.' - and, with the movement log on, as a row of wheelly_movements.csv whose outcome is angle-taught (a confirmed asterisk) or angle-set (a typed value): the new angle under target, the old one under angle, the change under error. That is the history of the corrections: an angle that keeps moving night after night means something in the mechanics is moving.
• Kept by the wheel only until it is switched off: press 'Save to the wheel' to keep them. Restarting the wheel without saving brings back the last saved calibration, which is the way to undo an experiment.
• A value outside 0-360 is refused by the wheel: the row goes to Alert, the old value stays, and the log says why. Refused too while the wheel is moving.
• A wheel turned by hand is not followed by its row (only the steps are): to teach where the hand left it, type the angle shown in WHEELLY_POSITION into the row and press Set.
• The arrow stays on the slot while the wheel is stepped off it to centre it. INDI cannot colour a field, and a label reaches the client only when the property is defined, so the driver defines the rows again - and with them the properties after them in this tab, which would otherwise end up above them - only at the end of a step, at a change of slot and at a teach, never while the wheel is simply watched.
• A wheel never taught has the slots evenly spaced (0, 72, 144, 216 and 288 degrees on a five-slot wheel): usable, but not a calibration.
• One property per slot, not a single WHEELLY_ANGLES with one Set for all of them and a separate 'Save position' button (WHEELLY_TEACH): the Set on the starred row does what that button would. A wheel saved by an older firmware with a 'Rotation trim' per slot gets the trims added to its angles, once, at the first start of the current firmware. The sweep viewer marks these angles on the magnet sweep.

2

Wheelly WHEELLY_ANGLE_2

Slot 2's calibration angle, with its own Set: it works as slot 1's row (WHEELLY_ANGLE_1), which says how.

3

Wheelly WHEELLY_ANGLE_3

Slot 3's calibration angle, with its own Set: it works as slot 1's row (WHEELLY_ANGLE_1), which says how.

4

Wheelly WHEELLY_ANGLE_4

Slot 4's calibration angle, with its own Set: it works as slot 1's row (WHEELLY_ANGLE_1), which says how.

5

Wheelly WHEELLY_ANGLE_5

Slot 5's calibration angle, with its own Set: it works as slot 1's row (WHEELLY_ANGLE_1), which says how.

Step back

Wheelly WHEELLY_JOG_DOWN

Moves the wheel back by a step, towards decreasing angles, to centre the filter of the current slot; WHEELLY_JOG_UP goes the other way, and the Set on the slot's row, which follows the steps, keeps the result. The first button is one slot pitch, 360 degrees divided by the number of slots (72 on a five-slot wheel), which goes to the neighbouring filter; the others are 10, 1 and 0.1 degrees. Each step is a move TO the angle read now minus the step, made by the wheel with its closed loop - the same legs as a filter change, with the clutch tyre's play taken up - not a count of motor steps: the tyre swallows about 0.6 degrees before the disc moves. Each button acts once and springs back.

• Busy while the wheel moves, then Ok, and the log says where it is: 'The wheel is at A degrees, E degrees from where the step asked.' Alert if it did not get there (log: 'The wheel did not get where the step asked ...', followed by the line that suggests checking that the wheel's detent was removed), or if the wheel refused the step.
• A step that did not cover at least half of itself is a failure, never a warning: the Alert band of a filter change is wider than the small steps, so a 0.5 degree step that did not move at all would otherwise be reported as done.
• A step is not a filter change: FILTER_SLOT stays as it is, and the step always goes its own way, whatever WHEELLY_DIRECTION says - one way only, a step against it would go round the whole wheel. On a mechanism stiffer one way a step the stiff way may stall.
• The pitch lands on the next filter on a wheel whose angles are evenly spaced; the label follows the number of slots. On a two-slot wheel the pitch is half a turn, and it goes the way its button says.
• Refused while the wheel is moving (log: 'Cannot move the wheel by a step while it is moving ...').
• Two rows and not one: KStars shows more than four exclusive buttons as a drop-down menu. There is no 0.05 degree step: it is below what the sensor can read (one count is 0.088 degrees), so a 0.05 step that did not move could not be told from one that did.

Step forward

Wheelly WHEELLY_JOG_UP

Moves the wheel forward by a step, towards increasing angles: the mirror of WHEELLY_JOG_DOWN, which says how a step works.

• Busy while the wheel moves, then Ok or Alert, as WHEELLY_JOG_DOWN.

Calibration actions

Wheelly WHEELLY_SAVE

Everything you change in the calibration panel lives in the wheel's working memory until you press 'Save to the wheel'; saving is a deliberate act, so you can experiment freely. The button acts once and springs back. The same button is in Options, under 'Wheel configuration' (WHEELLY_CONFIG).

• Ok when the wheel saved, Alert when it could not; the reason is in the log (for instance 'The wheel could not save to its memory.').
• The position of a slot is taught with the Set on its row of the angles (WHEELLY_ANGLE_1 and the others), so there is no 'Set current slot here' button here, and no trims to clear.

Tolerances

Wheelly WHEELLY_TOLERANCE

How precise a filter change has to be, and how hard the wheel tries. After a move the wheel compares the residual error with two thresholds: within Good it is a success; between Good and Alert it is a success with a warning in the log, and imaging continues; beyond Alert it retries, up to Max retries, and then declares the failure, which stops the Ekos sequence.

• Limits in the panel: 0.01 to 45 degrees (step 0.01) for both tolerances, 0 to 20 retries (step 1). The wheel also requires Good not larger than Alert; otherwise it refuses the three values, the property goes to Alert and the log explains.
• Retries are also capped in time: the wheel stops retrying after 25 s from the start of the move.
• Kept by the wheel until switched off; press 'Save to the wheel' to keep them.
• Also saved in the INDI configuration, but at connection the values shown are the ones read from the wheel; the saved copy is sent to the wheel only when the configuration is loaded (CONFIG_PROCESS, Load).
• For scale: one count of the AS5600 is 0.088 degrees; the wheel averages 8 readings per measurement. One degree of disc moves a filter about 0.9 mm on a filter circle of about 50 mm radius (an estimate). The defaults allow for the last half degree to one degree that the drive's TPU tyre absorbs; tighter values can be tried once the movement log shows the real errors.

Hardware check

Wheelly WHEELLY_DIAG

Asks the wheel one question: is it really talking to its sensor and to its motor driver? The answer goes to the log panel. It is the first thing to press when the wheel does something unexpected: a loose wire on the motor driver shows up as 'the motor does not turn' and sends you looking in the wrong places.

• Log lines, in order: 'Asking the wheel whether it can really talk to its sensor and its motor driver:', then 'AS5600 at 0x36: responding' with a line 'STATUS md=... AGC=... MAG=...', or 'AS5600 at 0x36: SILENT' with a hint to check the wiring and the VDD5V-VDD3V3 jumper on the module.
• When the magnitude is below 350 an extra line says the magnet is too far or off centre.
• Then the motor driver: '<chip> over UART: responding, run X mA, hold Y mA', or '<chip> over UART: SILENT - check VM at the driver, then the 1k on the single wire'. The chip name (TMC2208 or TMC2209) is read from the chip itself; a silent chip cannot say which it is, so that line reads 'TMC2208/2209 over UART: SILENT'.
• The lines of this check are firmware text and are not translated.
• Ok when the wheel answered, Alert when it did not.
• It does not move the wheel.

Magnet sweep

Wheelly WHEELLY_SWEEP

The magnet sweep: the wheel turns once all the way round, one slot at a time, always in the same direction, and the driver records the sensor magnitude and the angle at every poll. At the end it writes them to a CSV file in the sweeps folder. The smaller the variation over the turn, the better the magnet is centred: use it before and after adjusting the sensor gap or the magnet.

• The wheel really moves: do it with the cover open, never during a sequence (log: 'Turning all the way round and measuring the magnet at every step ...'). FILTER_SLOT goes Busy at each step.
• One jump per slot (5 on a factory wheel): the wheel ends on the slot it started from.
• During the sweep the driver polls every 100 ms instead of every POLLING_PERIOD, to get enough samples.
• Refused, with Alert, while a filter change or another sweep is running.
• At the end: Ok, the samples are written to the sweeps folder, and the log gives the number of samples, the magnitude minimum and maximum and the excursion in counts and in percent, then the file path.
• To see the sweep as a curve, open the file with the sweep viewer, https://teoteo.github.io/Wheelly/tools/sweep.html: a single page, to use online or saved and opened from the disk, with no network. It draws the magnitude against the angle with the taught angles marked, and several sweeps over each other, to compare a before and an after. The file stays on your computer. It is a plain CSV too, which any spreadsheet opens.
• The driver draws nothing itself: an INDI driver measures and reports, and the picture is the viewer's job.
• If a jump fails or times out, or fewer than 4 samples were taken, nothing is written and the property goes to Alert (log: 'The sweep stopped before finishing the turn ...').
• Each jump is an ordinary move, so it is also written in the movement log when that is on.

Sweeps folder

Wheelly WHEELLY_SWEEP_DIR

The folder where the driver writes each sweep. The default is the Documents folder in the home directory of the computer running the driver (on a Raspberry, the Raspberry's, not your laptop's). Point it elsewhere, for example to an external disk, if you keep your data there.

• Each sweep gets its own file, named YYYY-MM-DD_HH-MM-SS_wheelly_sweep.csv in local time, so a sweep before and one after an adjustment can be compared; nothing is overwritten.
• The file: header lines starting with '#' - the number of slots and their taught angles - then 'angle_deg,magnitude' and one line per sample.
• When you change it the driver creates the folder (one level only) and checks it can write there. If not, the property turns red and the log says 'The folder ... cannot be used right now: ... The sweeps will not be saved until it can.' The value is kept anyway (a disk may simply not be mounted yet).
• Saved in the INDI configuration immediately.
• An empty folder means the default.

Movement log

Wheelly WHEELLY_LOG

Turns on or off the movement log: a CSV file with one line per finished filter change, to open in a spreadsheet when you want to see how precise the wheel is over a night or over months. Off by default.

• The file is ~/.indi/wheelly_movements.csv on the computer running the driver, fixed; its path is always shown in 'Files on disk'. New lines are appended; nothing is deleted.
• Columns: timestamp (UTC, ISO 8601), slot (asked for), target (target angle, degrees), angle, error (degrees), retries, outcome (arrived, warning, failed or timeout), agc, magnitude.
• The choice is saved in the INDI configuration and applied at the next connection.
• If the file cannot be opened the log says why and the switch goes back to Off.

Files on disk

Wheelly WHEELLY_FILES · read-only

Where the two files the driver writes are, so the paths are not lost in the log: the movement log and the last sweep. Both paths are on the computer running the driver.

• Read-only.
• 'Last sweep' shows 'not written yet' after each start of the driver, until a sweep is done; older sweeps stay in the sweeps folder.
• Alert when the last sweep could not be written; the reason is in the log ('Cannot write the sweep to ...').