전체 항목

예를 들어 텔레그램 봇을 설정에 등록하면 동작 → 텔레그램 메시지에서 해당 봇을 선택하여 사용할 수 있습니다.

설정 메뉴의 전체 항목은 다음과 같습니다. 분류는 화면의 항목 그룹과 같으며, 목록의 순서도 화면과 같습니다.

이하에서는 사용 빈도가 높은 항목을 자세히 설명합니다.

변수

설정 → 변수에서 프로젝트 전역 변수를 만들고 관리합니다. 변수를 만들 때 여덟 가지 타입 중 하나를 선택합니다.

타입은 나중에 변경할 수 있습니다. 변경하면 해당 변수를 사용하는 블록이 새 타입에 맞게 조정되며, 타입이 맞지 않게 된 연결은 해제됩니다.

배열을 선택하면 같은 타입의 값 여러 개를 한 변수에 저장합니다. 배열 차원은 1~3차원, 전체 크기(각 차원 크기의 곱)는 65,536 이하로 설정할 수 있습니다. 변수를 만들 때 초기값을 지정하면 실행 시작 시 그 값으로 시작합니다.

컬렉션

컬렉션은 값 여러 개를 담아 두고 동작으로 추가·조회·삭제하는 저장소입니다. 컬렉션 타입에서 순서대로 담는 리스트와 키로 찾는 맵 중 하나를 선택하고, 담을 값 타입을 지정합니다. 맵은 키 타입도 함께 지정합니다. 키 타입과 값 타입은 변수 타입 여덟 가지와 같습니다.

크기 제한을 켜면 최대 크기를 넘겨 저장할 수 없습니다. 리스트에서 크기 제한과 함께 원형 버퍼를 켜면 최대 크기를 넘길 때 가장 오래된 값을 지우고 새 값을 넣으므로, 큐나 스택처럼 사용할 수 있습니다.

데이터베이스

설정 → 데이터베이스에서 연결을 등록하면 동작 → 데이터베이스에서 선택하여 데이터를 저장하거나 조회할 수 있습니다. 타입에 따라 입력 항목이 달라집니다.

SQL 계열 데이터베이스는 동작에서 로그인 → 쿼리 실행 → 로그아웃 순서로 사용합니다. 패스워드와 연결 문자열, 웹 API 키는 컨트롤러에 암호화되어 저장됩니다.

GPIO

설정 → GPIO에서는 GPIO 샘플 시간과 외부 GPIO 를 설정합니다. 샘플 시간은 GPIO 입력 변화를 감시하는 시간 간격으로, 짧을수록 정밀하지만 CPU 점유율이 높아지며, 프로젝트 디바이스가 라즈베리파이(0~4)인 경우에만 표시됩니다. 1~10μs 중에서 선택하며 일반적으로 5μs 가 적당합니다. 이 값은 PWM 모니터링, 고속 카운터처럼 GPIO 입력의 변화를 감지하는 장치의 정밀도를 결정하므로, 샘플 시간보다 짧은 변화는 감지되지 않습니다.

일반 PC 와 같이 보드에 GPIO 핀이 없거나 보드의 핀이 부족한 경우에는 외부 GPIO에 FT232H, MCP2221, NUMATO 의 USB-GPIO 어댑터를 등록하여 사용할 수 있습니다. FT232H 와 MCP2221 은 인덱스로 장치를 구분하고(스캔 버튼으로 검색, 장치가 하나면 기본값 사용), NUMATO 는 채널 수에 맞는 모델과 시리얼 포트를 지정합니다.

카메라

설정 → 카메라에서 카메라 소스를 선택하여 등록합니다.

• CSI/USB: 컨트롤러에 직접 연결된 카메라(라즈베리파이 카메라 모듈, USB 웹캠)를 사용합니다.
• ONVIF: 같은 네트워크의 IP 카메라를 검색하여 등록합니다. 계정이 필요한 카메라는 카메라 선택 창에서 사용자와 비밀번호를 입력합니다.
• RTSP(IP 카메라의 영상 전송 표준): 스트림 주소를 직접 입력하여 등록합니다. 주소는 카메라 설명서에서 확인하며, 인증이 필요하면 사용자와 비밀번호를 함께 입력합니다.

카메라를 거꾸로 또는 옆으로 설치한 경우에는 방향에서 90°, 180°, 270° 회전과 좌우·상하 반전, 회전과 반전을 조합한 값을 선택하여 영상을 바로잡습니다. 관심 영역 (ROI) 에서는 화면의 일부 영역을 여러 개 정의해 두고 카메라 캡처와 AI 분석에서 골라 사용할 수 있습니다.

AI 분석기

설정 → AI 분석기에서 분석할 카메라와 GPU 가속 사용 여부를 설정합니다.

모드는 분석 속도와 정밀도의 균형을 결정합니다. 라즈베리파이와 같이 성능이 낮은 기기에는 빠름, PC·Jetson 과 같은 고성능 기기에는 정확, 그 사이에는 균형을 권장합니다. 선택 가능한 값은 AI 모델에 따라 다릅니다. 객체 감지, 얼굴 감지, 얼굴 인식, 화재 감지, 라인 크로싱 카운터는 세 가지 모두 선택할 수 있고, 자세 추정, 손 추적, 번호판 인식, 커스텀 이상 감지는 빠름과 정확만 지원하며, 나머지 모델은 단일 모델이므로 모드 항목이 표시되지 않습니다.

검출 FPS 는 초당 분석 횟수의 상한입니다. 기본값은 5이며 자세 추정, 손 추적, 동작 인식, 손동작 인식, 라인 크로싱 카운터는 10, 연산량이 많은 커스텀 이상 감지는 1입니다. 0은 제한 없음을 의미합니다. 컨트롤러의 부하가 높다면 모드보다 이 값을 먼저 낮추는 방법이 효과적입니다.

LLM AI

설정 → LLM AI에서 OpenAI, Anthropic, Google Gemini, Ollama 또는 OpenAI 호환 엔드포인트를 등록합니다. 여러 제공자를 등록해 두고 LLM AI 질의 동작마다 다른 제공자를 선택할 수 있습니다.

모델은 제공자별 목록에서 선택하거나 이름을 직접 입력합니다. 목록에 없는 새 모델이 나왔을 때도 이름만 입력하면 사용할 수 있습니다. Ollama 와 OpenAI 호환은 모델 이름을 직접 입력하고 서버 주소를 함께 지정하며(Ollama 기본값은 http://localhost:11434/v1), 로컬에서 실행되는 Ollama 는 API 키가 필요하지 않습니다. 나머지 제공자는 각 서비스에서 발급한 API 키를 입력합니다.

이미지 다운스케일은 이미지를 첨부하여 질의할 때 축소할 비율입니다. 기본값은 100%(원본)이며, 낮추면 업로드 속도와 비용이 줄고 높이면 세부가 보존됩니다. 카메라 해상도가 낮은 경우에는 100% 를 권장합니다.

텍스트 음성 변환 · 음성 텍스트 변환

텍스트 음성 변환(TTS)과 음성 텍스트 변환(STT) 은 타입에 따라 두 갈래로 나뉩니다.

• On Device: 컨트롤러에 내장된 모델로 변환합니다. 인터넷 연결과 API 키가 필요하지 않습니다. 언어를 선택하면 그 언어의 모델 목록이 표시되며, 선택한 모델은 처음 실행할 때 자동으로 내려받습니다.
• Google Cloud · OpenAI · ElevenLabs: 온라인 서비스로 변환합니다. API 키가 필요하며, 키는 컨트롤러에 암호화되어 저장됩니다. TTS 는 네 가지 타입을, STT 는 On Device, Google Cloud, OpenAI 세 가지를 지원합니다.

모델 목록에서 CUSTOM 을 선택하면 직접 준비한 모델 폴더의 경로를 입력할 수 있습니다. 이때 내려받은 폴더의 이름을 바꾸면 모델을 인식하지 못하므로 원래 이름을 그대로 유지합니다.

음성 텍스트 변환에는 말의 시작과 끝을 판정하는 두 항목이 있습니다. 음성 감지 임계값은 5~90% 범위로, 낮추면 작은 소리까지 감지하지만 배경 소음도 함께 인식합니다(조용한 환경 20~40%, 일반 환경 30~50%, 시끄러운 환경 50~70% 권장). 음성 완료 시간은 말이 끝났다고 판단할 침묵 시간이며 0.3~5초 범위입니다(빠른 대화 0.5초, 일반 대화 1초, 신중한 발언 2초 권장).

통신

통신 항목은 컨트롤러가 외부 장비나 서버와 주고받을 연결을 미리 등록하는 곳입니다. 등록한 연결은 같은 이름의 동작에서 선택하여 사용합니다.

MQTT 클라이언트

호스트와 포트를 입력합니다. 기본 포트는 암호화를 사용하지 않을 때 1883, SSL/TLS 를 사용할 때 8883 입니다. 클라이언트 ID 는 브로커 안에서 고유해야 하며, 비워 두면 자동으로 생성됩니다. 브로커가 인증을 요구하면 사용자 인증을 켜고 아이디와 패스워드를 입력하고, SSL/TLS 암호화를 켜면 클라이언트 인증서, 클라이언트 개인키, CA 인증서를 등록합니다.

Will 메시지는 연결이 비정상적으로 끊겼을 때 브로커가 대신 발행할 메시지입니다. 토픽과 메시지, QoS, 메시지 보존 여부를 설정합니다. QoS 는 0이 응답을 확인하지 않고, 1이 응답이 올 때까지 재전송하며(중복 가능), 2가 정확히 한 번의 전달을 보장합니다. 숫자가 커질수록 신뢰성이 높아지지만 네트워크 사용량도 늘어납니다.

모드버스

타입에서 RTU Master, RTU Slave, TCP Master, TCP Slave 중 하나를 선택합니다. RTU 는 시리얼 포트와 Baud rate, Parity bit, Stop bit, Data bits 를, TCP 는 IP 주소와 포트(기본 502)를 입력합니다. Master 는 Unit ID(1~247)로 대상 장비를 지정하고, TCP Slave 는 동시 접속할 Master 의 최대 연결 갯수(기본 16)를 설정합니다.

Slave 로 동작할 때는 Register 크기와 Bit 크기를 정하고 각 주소에 변수를 매핑합니다. Grablo 의 Slave 메모리는 입력과 출력을 구분하지 않고 Register 영역과 Bit 영역으로만 구성됩니다. Coils 와 Discrete Inputs 는 Bit 영역을, Holding Registers 와 Input Registers 는 Register 영역을 사용하며 주소는 0부터 시작합니다.

OPC UA 클라이언트

호스트와 포트(기본 4840), 응답 타임아웃을 입력합니다. 서버가 인증을 요구하면 사용자 인증을 켜고 아이디와 패스워드를 입력합니다. SSL/TLS 암호화를 켜면 인증서 파일과 개인키 파일, 암호화 방법, 보안 모드를 설정합니다. 인증서와 개인키는 Grablo 가 기본 파일을 제공하므로 그 파일을 서버에 등록하여 사용할 수 있습니다.

사용자 정의 통신

시리얼 통신, TCP 클라이언트와 서버, UDP 클라이언트와 서버, 공유 메모리, 웹소켓 클라이언트, 블루투스 클라이언트와 서버 아홉 가지를 지원합니다. 시리얼은 포트와 통신 조건을, TCP·UDP· 웹소켓은 호스트와 포트를, 공유 메모리는 이름과 크기를, 블루투스는 로컬 HCI 인덱스와 리모트 MAC 주소를 입력합니다.

수신 타임아웃은 마지막 바이트를 받은 뒤 다음 바이트를 기다리는 최대 시간입니다. 이 시간을 넘기면 더 이상 받을 데이터가 없다고 판단하므로, 프레임 단위로 데이터를 주고받을 때 이 값이 수신 성패를 가릅니다. 공유 메모리는 이름이 상대와 같아야 하며, 같은 이름의 공유 메모리가 이미 있으면 그것을 사용합니다.

이메일 클라이언트

SMTP 서버의 호스트와 아이디, 패스워드, 발신자 주소와 발신자 이름을 입력합니다. 포트는 보안 방식에 따라 기본값이 함께 바뀝니다.

데이터 로깅

설정 → 데이터 로깅에서 채널을 만들고 기록할 변수를 연결합니다. 한 채널에 여러 변수를 연결할 수 있으며, 같은 주기에 기록된 값들은 같은 시각으로 저장됩니다. 자동 로깅이 켜져 있으면(기본값) 로깅 주기마다(기본값 1분) 변수 값이 컨트롤러의 데이터베이스에 저장됩니다. 기록된 데이터는 대시보드의 기록 차트·기록 테이블 위젯에서 조회합니다.

주기 저장과 별개로, 동작의 데이터 로깅 타입을 사용하면 특정 시점의 값을 한 건씩 기록할 수 있습니다. 이벤트 시점만 기록하려면 자동 로깅을 끄고 동작 기록만 사용합니다.

제한 방식은 기록 보존 한도를 결정합니다. 기본값은 없음(무제한)이며 용량(기본 100MB), 갯수(기본 100,000건), 기간(기본 30일) 중 하나를 선택하면 한도를 초과할 때 오래된 기록부터 삭제됩니다. 장기간 운영할 채널은 생성 시점에 제한 방식을 함께 설정하는 것을 권장합니다.

Home Assistant · Zigbee

설정 → Home Assistant에서 연결을 등록하면 Home Assistant 엔티티를 읽고 제어하거나 Grablo 변수를 새 엔티티로 노출할 수 있습니다. 애드온 모드는 기본으로 켜져 있으며, Grablo 를 Home Assistant 애드온으로 설치한 경우(2부)에는 이 상태에서 서버 주소나 토큰 없이 자동으로 연결됩니다.

애드온이 아닌 별도의 컨트롤러에서 연결하려면 애드온 모드를 끄고 HA 서버 주소와 포트(기본 8123), Access Token 을 입력합니다. 토큰은 Home Assistant 의 프로필 > Long-Lived Access Tokens 에서 생성하며, HA 가 HTTPS 로 운영 중이면 HTTPS/WSS 사용을 함께 켭니다.

Zigbee 장치는 Zigbee2MQTT(Zigbee 장치를 MQTT 로 중계하는 오픈소스 브리지)로 페어링한 장치를 등록하며 조명, 스위치, 센서 등 3,400여 종의 장치를 지원합니다. 페어링과 장치 선택, 삭제는 설정 화면의 장치 관리 창에서 수행합니다.