Skip to main content

IActor

The core interface for all actors in ControlBee. Actors are the fundamental building blocks of the system, representing autonomous entities that encapsulate state, process messages, and interact with hardware.

Namespace: ControlBee.Interfaces

Overview​

Every actor in ControlBee implements this interface, whether it's a simple sensor reader or a complex multi-axis positioning system. The interface provides the foundation for:

  • Message-based communication between actors
  • Introspection of actor state and capabilities
  • Item management for variables, devices, and functions
  • Position-axis mapping for motion control

Actors are typically created by inheriting from the Actor base class, which implements this interface and provides additional functionality for state management, device integration, and peer communication.

Properties​

NameTypeDescription
NamestringThe unique name of the actor instance (e.g., "Stage0", "Vision1"). Used for identification and message routing.
TitlestringThe human-readable display title for UI presentation (e.g., "Main Stage", "Camera #1").

Methods​

Send​

Sends a message to the actor for processing.

Guid Send(Message message);

Parameters:

  • message — The message to send, containing a name and optional data payload.

Returns: A Guid identifying the sent message, useful for tracking and correlation.

Description:

Messages are the primary communication mechanism between actors. The Send method places a message in the actor's queue, where it will be processed by the current state's OnProcess method.

Usage Example:

using Dict = System.Collections.Generic.Dictionary<string, object?>;

// Send a simple command message
var messageId = targetActor.Send(new Message(this, "Start"));

// Send a message with data payload
var messageId = targetActor.Send(new Message(this, "SetSpeed", 100.0));

// Send a complex data payload using Dict
var messageId = targetActor.Send(new Message(this, "ProcessCell", new Dict
{
    ["Row"] = 5,
    ["Col"] = 3
}));

See Also:

GetItems​

Returns all items exposed by the actor, including variables, devices, and functions.

(string itemPath, Type type)[] GetItems();

Returns: An array of tuples, each containing an item's path and its type.

Description:

Items are the actor's public interface - properties that can be accessed, configured, or monitored from outside the actor. This includes:

  • Variables - Configuration parameters and runtime state
  • Devices - Hardware interfaces (axes, I/O, sensors)
  • Functions - Callable methods exposed for external use

The item path follows a hierarchical naming convention, such as "LoadSpeed" or "X.CommandPosition".

Usage Example:

// Inspect an actor's items
var items = actor.GetItems();
foreach (var (path, type) in items)
{
    Console.WriteLine($"{path}: {type.Name}");
}

// Output example:
// LoadSpeed: Double
// LoadPosX: Position1D
// X: IAxis
// Vacuum: IDigitalOutput
// ProcessCycle: Function

Common Use Cases:

  • UI generation - automatically create configuration interfaces
  • Diagnostics - inspect actor state and capabilities
  • Recipe management - identify which variables to save/load
  • Testing - enumerate testable properties

GetItem​

Retrieves a specific item by its path.

IActorItem? GetItem(string itemPath);

Parameters:

  • itemPath — The hierarchical path to the item (e.g., "LoadSpeed" or "X.CommandPosition").

Returns: The IActorItem if found, or null if the path doesn't exist.

Description:

Retrieves an item wrapper that provides metadata and value access. The returned IActorItem allows you to:

  • Read and write the item's value
  • Access type information
  • Check permissions and visibility
  • Monitor for changes

Usage Example:

// Get a variable item
var speedItem = actor.GetItem("LoadSpeed");
if (speedItem != null)
{
    Console.WriteLine($"Current speed: {speedItem.Value}");
    speedItem.Value = 150.0;  // Modify the value
}

// Get a nested device property
var posItem = actor.GetItem("X.CommandPosition");
if (posItem != null)
{
    Console.WriteLine($"X position: {posItem.Value}");
}

// Handle missing item
var item = actor.GetItem("NonExistent");
if (item == null)
{
    Console.WriteLine("Item not found");
}

Common Use Cases:

  • Recipe loading - set variable values from stored configurations
  • Remote control - modify actor parameters at runtime
  • Data logging - record variable changes
  • Property binding - connect UI controls to actor properties

GetFunctions​

Lists the names of all callable functions exposed by the actor.

string[] GetFunctions();

Returns: An array of function names available for invocation.

Description:

Functions are methods that actors expose for external invocation, typically representing high-level operations or commands. Unlike message passing (which is asynchronous), functions can be called synchronously and may return values.

Usage Example:

// Discover available functions
string[] functions = actor.GetFunctions();
foreach (string funcName in functions)
{
    Console.WriteLine($"Available: {funcName}");
}

// Output example:
// Available: InitializeAxes
// Available: TeachPosition
// Available: ProcessCycle
// Available: EmergencyStop

Common Use Cases:

  • UI button generation - create buttons for each function
  • Manual control panels - provide operator controls
  • Testing and debugging - manually trigger operations
  • Scripting - allow external scripts to invoke operations

Note: While functions provide synchronous invocation, prefer message passing for inter-actor communication to maintain loose coupling and support for distributed systems.

GetAxisItemPaths​

Returns the axis item paths associated with a given position variable.

string[] GetAxisItemPaths(string positionItemPath);

Parameters:

  • positionItemPath — The path of the position variable (e.g., "LoadPosX" or "TargetXYZ").

Returns: An array of axis item paths that are mapped to this position (e.g., ["X"] or ["X", "Y", "Z"]).

Description:

Position variables in ControlBee are mapped to physical motion axes through the PositionAxesMap. This method retrieves the axis associations for a given position, enabling:

  • UI generation - show which axes will move for a position
  • Teaching - know which axes to read when teaching a position
  • Validation - verify axis availability before motion
  • Visualization - highlight affected axes in motion simulations

Usage Example:

// Find axes for a position
string[] axes = actor.GetAxisItemPaths("LoadPosX");
Console.WriteLine($"LoadPosX moves axes: {string.Join(", ", axes)}");
// Output: LoadPosX moves axes: X

// Multi-axis position
string[] axes = actor.GetAxisItemPaths("TargetXYZ");
Console.WriteLine($"TargetXYZ moves axes: {string.Join(", ", axes)}");
// Output: TargetXYZ moves axes: X, Y, Z

// Position teaching example
var axes = actor.GetAxisItemPaths("LoadPosX");
foreach (var axisPath in axes)
{
    var axisItem = actor.GetItem(axisPath);
    if (axisItem?.Value is IAxis axis)
    {
        Console.WriteLine($"Axis {axisPath} at position: {axis.ActualPosition}");
    }
}

Common Use Cases:

  • Position teaching - read current axis positions and store in position variable
  • Motion preview - show which axes will move before executing
  • Axis validation - ensure all required axes are available and not in error
  • UI generation - display axis associations in configuration screens

See Also:

Usage in Actor Development​

When creating custom actors, you typically inherit from the Actor base class rather than implementing IActor directly:

public class MyStageActor : Actor
{
    // Variables (automatically become items)
    public Variable<double> Speed = new(VariableScope.Local, 100.0);
    public Variable<Position1D> LoadPos = new(VariableScope.Local);

    // Devices (automatically become items)
    public IAxis X;
    public IDigitalOutput Vacuum;

    // Constructor receives ActorConfig
    public MyStageActor(ActorConfig config) : base(config)
    {
        X = config.AxisFactory.Create();
        Vacuum = config.DigitalOutputFactory.Create();

        // Map position to axis
        PositionAxesMap.Add(LoadPos, [X]);
    }

    // Exposed function (automatically discoverable)
    [Function]
    public void TeachLoadPosition()
    {
        LoadPos.Value.TeachCurrent();
    }

    // Message processing via state machine
    public override void Start()
    {
        base.Start();
        SetState(new IdleState(this));
    }
}

The Actor base class:

  • Implements IActor interface
  • Provides state machine management
  • Handles message queuing and processing
  • Manages item registration and discovery
  • Supports peer communication
  • Integrates with variable system
  • Provides lifecycle hooks (Start, Stop, Dispose)

See Also​