IActor

ControlBee의 모든 액터를 위한 핵심 인터페이스입니다. 액터는 상태를 캡슐화하고, 메시지를 처리하며, 하드웨어와 상호 작용하는 자율적인 개체를 나타내는 시스템의 기본 구성 요소입니다.

네임스페이스: ControlBee.Interfaces

개요

ControlBee의 모든 액터는 이 인터페이스를 구현합니다. 간단한 센서 리더든 복잡한 다축 위치 결정 시스템이든 상관없이 말입니다. 이 인터페이스는 다음을 위한 기반을 제공합니다:

액터 간 메시지 기반 통신
액터 상태 및 기능의 내부 검사
변수, 장치 및 함수를 위한 항목 관리
모션 제어를 위한 위치-축 매핑

액터는 일반적으로 이 인터페이스를 구현하고 상태 관리, 장치 통합 및 피어 통신을 위한 추가 기능을 제공하는 Actor 기본 클래스를 상속하여 생성됩니다.

속성

이름	타입	설명
`Name`	`string`	액터 인스턴스의 고유 이름입니다(예: "Stage0", "Vision1"). 식별 및 메시지 라우팅에 사용됩니다.
`Title`	`string`	UI 표시를 위한 사람이 읽을 수 있는 제목입니다(예: "메인 스테이지", "카메라 #1").

메서드

Send

액터에게 처리할 메시지를 보냅니다.

Guid Send(Message message);

매개변수:

message — 이름과 선택적 데이터 페이로드를 포함하는 전송할 메시지입니다.

반환값: 전송된 메시지를 식별하는 Guid로, 추적 및 상관관계에 유용합니다.

설명:

메시지는 액터 간의 주요 통신 메커니즘입니다. Send 메서드는 메시지를 액터의 큐에 배치하며, 현재 상태의 OnProcess 메서드에서 처리됩니다.

사용 예시:

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

// 간단한 명령 메시지 전송
var messageId = targetActor.Send(new Message(this, "Start"));

// 데이터 페이로드와 함께 메시지 전송
var messageId = targetActor.Send(new Message(this, "SetSpeed", 100.0));

// Dict를 사용한 복잡한 데이터 페이로드 전송
var messageId = targetActor.Send(new Message(this, "ProcessCell", new Dict
{
    ["Row"] = 5,
    ["Col"] = 3
}));

참고:

GetItems

변수, 장치 및 함수를 포함하여 액터가 노출하는 모든 항목을 반환합니다.

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

반환값: 각 항목의 경로와 타입을 포함하는 튜플 배열입니다.

설명:

항목은 액터의 공개 인터페이스로, 액터 외부에서 액세스, 구성 또는 모니터링할 수 있는 속성입니다. 여기에는 다음이 포함됩니다:

변수 - 구성 매개변수 및 런타임 상태
장치 - 하드웨어 인터페이스(축, I/O, 센서)
함수 - 외부 사용을 위해 노출된 호출 가능한 메서드

항목 경로는 "LoadSpeed" 또는 "X.CommandPosition"과 같은 계층적 명명 규칙을 따릅니다.

사용 예시:

// 액터의 항목 검사
var items = actor.GetItems();
foreach (var (path, type) in items)
{
    Console.WriteLine($"{path}: {type.Name}");
}

// 출력 예시:
// LoadSpeed: Double
// LoadPosX: Position1D
// X: IAxis
// Vacuum: IDigitalOutput
// ProcessCycle: Function

일반적인 사용 사례:

UI 생성 - 구성 인터페이스 자동 생성
진단 - 액터 상태 및 기능 검사
레시피 관리 - 저장/로드할 변수 식별
테스트 - 테스트 가능한 속성 열거

GetItem

경로를 통해 특정 항목을 검색합니다.

IActorItem? GetItem(string itemPath);

매개변수:

itemPath — 항목의 계층적 경로입니다(예: "LoadSpeed" 또는 "X.CommandPosition").

반환값: 찾은 경우 IActorItem, 경로가 존재하지 않으면 null입니다.

설명:

메타데이터 및 값 액세스를 제공하는 항목 래퍼를 검색합니다. 반환된 IActorItem을 사용하여 다음을 수행할 수 있습니다:

항목의 값 읽기 및 쓰기
타입 정보에 액세스
권한 및 가시성 확인
변경 사항 모니터링

사용 예시:

// 변수 항목 가져오기
var speedItem = actor.GetItem("LoadSpeed");
if (speedItem != null)
{
    Console.WriteLine($"현재 속도: {speedItem.Value}");
    speedItem.Value = 150.0;  // 값 수정
}

// 중첩된 장치 속성 가져오기
var posItem = actor.GetItem("X.CommandPosition");
if (posItem != null)
{
    Console.WriteLine($"X 위치: {posItem.Value}");
}

// 누락된 항목 처리
var item = actor.GetItem("NonExistent");
if (item == null)
{
    Console.WriteLine("항목을 찾을 수 없습니다");
}

일반적인 사용 사례:

레시피 로드 - 저장된 구성에서 변수 값 설정
원격 제어 - 런타임에 액터 매개변수 수정
데이터 로깅 - 변수 변경 사항 기록
속성 바인딩 - UI 컨트롤을 액터 속성에 연결

GetFunctions

액터가 노출하는 모든 호출 가능한 함수의 이름을 나열합니다.

string[] GetFunctions();

반환값: 호출에 사용할 수 있는 함수 이름의 배열입니다.

설명:

함수는 액터가 외부 호출을 위해 노출하는 메서드로, 일반적으로 높은 수준의 작업 또는 명령을 나타냅니다. 메시지 전달(비동기)과 달리 함수는 동기적으로 호출될 수 있으며 값을 반환할 수 있습니다.

사용 예시:

// 사용 가능한 함수 검색
string[] functions = actor.GetFunctions();
foreach (string funcName in functions)
{
    Console.WriteLine($"사용 가능: {funcName}");
}

// 출력 예시:
// 사용 가능: InitializeAxes
// 사용 가능: TeachPosition
// 사용 가능: ProcessCycle
// 사용 가능: EmergencyStop

일반적인 사용 사례:

UI 버튼 생성 - 각 함수에 대한 버튼 생성
수동 제어 패널 - 운영자 제어 제공
테스트 및 디버깅 - 작업을 수동으로 트리거
스크립팅 - 외부 스크립트가 작업을 호출하도록 허용

참고: 함수가 동기 호출을 제공하지만, 느슨한 결합을 유지하고 분산 시스템을 지원하기 위해 액터 간 통신에는 메시지 전달을 선호하세요.

GetAxisItemPaths

지정된 위치 변수와 관련된 축 항목 경로를 반환합니다.

string[] GetAxisItemPaths(string positionItemPath);

매개변수:

positionItemPath — 위치 변수의 경로입니다(예: "LoadPosX" 또는 "TargetXYZ").

반환값: 이 위치에 매핑된 축 항목 경로의 배열입니다(예: ["X"] 또는 ["X", "Y", "Z"]).

설명:

ControlBee의 위치 변수는 PositionAxesMap을 통해 물리적 모션 축에 매핑됩니다. 이 메서드는 주어진 위치에 대한 축 연결을 검색하여 다음을 가능하게 합니다:

UI 생성 - 위치에 대해 어떤 축이 움직일지 표시
티칭 - 위치를 티칭할 때 읽을 축 알기
유효성 검사 - 모션 전에 축 가용성 확인
시각화 - 모션 시뮬레이션에서 영향을 받는 축 강조 표시

사용 예시:

// 위치에 대한 축 찾기
string[] axes = actor.GetAxisItemPaths("LoadPosX");
Console.WriteLine($"LoadPosX가 움직이는 축: {string.Join(", ", axes)}");
// 출력: LoadPosX가 움직이는 축: X

// 다축 위치
string[] axes = actor.GetAxisItemPaths("TargetXYZ");
Console.WriteLine($"TargetXYZ가 움직이는 축: {string.Join(", ", axes)}");
// 출력: TargetXYZ가 움직이는 축: X, Y, Z

// 위치 티칭 예시
var axes = actor.GetAxisItemPaths("LoadPosX");
foreach (var axisPath in axes)
{
    var axisItem = actor.GetItem(axisPath);
    if (axisItem?.Value is IAxis axis)
    {
        Console.WriteLine($"축 {axisPath}의 위치: {axis.ActualPosition}");
    }
}

일반적인 사용 사례:

위치 티칭 - 현재 축 위치를 읽고 위치 변수에 저장
모션 미리보기 - 실행 전에 어떤 축이 움직일지 표시
축 유효성 검사 - 필요한 모든 축이 사용 가능하고 오류가 없는지 확인
UI 생성 - 구성 화면에 축 연결 표시

참고:

액터 개발에서의 사용

사용자 정의 액터를 생성할 때는 일반적으로 IActor를 직접 구현하지 않고 Actor 기본 클래스를 상속합니다:

public class MyStageActor : Actor
{
    // 변수 (자동으로 항목이 됨)
    public Variable<double> Speed = new(VariableScope.Local, 100.0);
    public Variable<Position1D> LoadPos = new(VariableScope.Local);

    // 장치 (자동으로 항목이 됨)
    public IAxis X;
    public IDigitalOutput Vacuum;

    // 생성자는 ActorConfig를 받습니다
    public MyStageActor(ActorConfig config) : base(config)
    {
        X = config.AxisFactory.Create();
        Vacuum = config.DigitalOutputFactory.Create();

        // 위치를 축에 매핑
        PositionAxesMap.Add(LoadPos, [X]);
    }

    // 노출된 함수 (자동으로 검색 가능)
    [Function]
    public void TeachLoadPosition()
    {
        LoadPos.Value.TeachCurrent();
    }

    // 상태 머신을 통한 메시지 처리
    public override void Start()
    {
        base.Start();
        SetState(new IdleState(this));
    }
}

Actor 기본 클래스:

IActor 인터페이스 구현
상태 머신 관리 제공
메시지 큐잉 및 처리 처리
항목 등록 및 검색 관리
피어 통신 지원
변수 시스템과 통합
수명 주기 후크 제공(Start, Stop, Dispose)

참고

액터 시스템 가이드 - 액터 개발 완벽 가이드
메시지 전달 가이드 - 액터 통신 패턴
변수 시스템 가이드 - 액터 상태 관리
상태 관리 가이드 - 상태 머신 패턴

개요​

속성​

메서드​

Send​

GetItems​

GetItem​

GetFunctions​

GetAxisItemPaths​

관련 인터페이스​

액터 개발에서의 사용​

참고​

개요

속성

메서드

Send

GetItems

GetItem

GetFunctions

GetAxisItemPaths

관련 인터페이스

액터 개발에서의 사용

참고