HostInModule

HostInModule is the entry point for a remote host commanding motion — a teleoperation link, a vision system, a hand controller. It turns a stream of positions arriving over a network into a setpoint the machine can safely follow.

Tracking is relative. The machine follows the host’s movement, not its absolute position, so the two do not need to start in the same place. You can engage tracking with the host anywhere and the machine will not jump.

flowchart LR
    i1(["input"]) --> B["HostInModule"]
    i2(["track/enable"]) --> B
    p1(["offset"]) --> B
    p2(["track/factor"]) --> B
    p3(["track/enableFader/fadeInTime, fadeOutTime"]) --> B
    p4(["track/syncFader/speed, enable"]) --> B
    p5(["track/watchdog/timeout, enable"]) --> B
    p6(["filter/order, omega, beta"]) --> B
    p7(["interpolator/sampleFactor"]) --> B
    B --> o1(["output"])
    B --> o2(["inputFilteredOffset"])
    B --> o3(["track/isTracking"])
    B --> o4(["track/enableFader/value"])
    B --> o5(["track/syncFader/value, fadeTime"])
    B --> o6(["filter/output"])
    B --> o7(["interpolator/output"])
    B --> o8(["reference, resetting"])

If the host stops writing track/enable, tracking is dropped after track/watchdog/timeout — a tenth of a second by default. This is the block’s main safety feature. Leave the watchdog on.

Two of the signals below are read-only in the tree. reference and resetting are published for you to watch, but only your application can set them. You cannot trigger a reset from the parameter tree.

Nothing here limits the machine’s speed. track/factor multiplies every movement the host makes, and it is not bounded. The limits belong in the blocks downstream — check they are in place before raising it.

An orientation instance has its signals under eulerZYX/ and quaternion/ instead of at the top level. Everything else below is the same.

Signals

Inputs

Outputs

Parameters

All are persistent and survive a controller restart. No parameters exist below this block beyond those listed.

Setup

1. Connect the host’s stream to input and have it write track/enable every cycle it wants tracking.

2. Leave track/enable false. Confirm output is stationary.

3. Set interpolator/sampleFactor to how many control cycles pass between host updates. If the host writes at 100 Hz on a 1 kHz task, that is 10.

4. Set filter/omega — go to Tuning.

5. Set track/factor to 1 for a first test, and check the machine’s own speed and position limits are configured, because this block has none.

6. Leave track/syncFader/enable false so tracking starts from wherever the machine is.

7. Have the host raise track/enable and move slowly.

   Step 7 gives a remote operator control of the machine. Start with a small track/factor, a slow host, and someone at the stop button.

8. Confirm output follows the host’s movement and track/isTracking is true.

9. Have the host stop writing track/enable entirely, and confirm tracking drops within track/watchdog/timeout.

Tuning

1. Set interpolator/sampleFactor first, from the host’s real update rate. Too low and you see a step at each host update; too high and the output is stale. Trace interpolator/output against input to check.
2. Set filter/omega from the noise on the host’s signal. Lower is smoother and adds more lag. Trace filter/output against interpolator/output.
3. Leave filter/order at 2 and filter/beta at 0.707 unless you have a reason. Order 1 has less lag and less rejection; order 0 is no filter at all.
4. Set track/factor from the working ratio you want between the host’s motion and the machine’s. Raise it in steps, checking the machine’s limits hold at each one.
5. Set the fade times from how abruptly you are willing for authority to change — a tenth of a second is a reasonable default for a hand controller.
6. Turn on the sync move only if the machine should meet the host’s absolute position. Set track/syncFader/speed to a safe approach speed and read track/syncFader/fadeTime back to see how long it will take.
7. Tighten track/watchdog/timeout as far as the host’s jitter allows. Too tight drops tracking on a network hiccup; too loose leaves the machine following a dead host for longer.

The output holds at its last value when tracking releases. It does not spring back.

A starting point for a hand controller at 100 Hz on a 1 kHz task:

track/factor                  = 1.0
track/enableFader/fadeInTime  = 0.1
track/enableFader/fadeOutTime = 0.1
track/syncFader/enable        = false
track/watchdog/enable         = true
track/watchdog/timeout        = 0.01
filter/order                  = 2
filter/omega                  = 15.7
filter/beta                   = 0.707
interpolator/sampleFactor     = 10

Limits and errors

This block logs nothing, ever. Every condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).