핵심 기능: MQTT 클라우드와 엣지 협업

MQTT 채널은 Edge-EMS Builder의 “클라우드와 엣지 협업” 기능을 구현합니다. 상향으로 엣지의 실시간 데이터와 결정 결과를 클라우드에 보고하고, 하향으로 클라우드가 전달한 전략을 받아 로컬 설정에 자동 적용합니다. 클라우드와 엣지 협업은 세 제품 등급의 기본 기능이며, 별도 비용이나 맞춤 개발이 필요한 고급 옵션이 아닙니다.

1. 연결 설정

MQTT 연결 설정은 특정 Broker에 연결하는 방법을 정의합니다.

매개변수	설명
`protocol`	`mqtt` / `mqtts`(TLS 활성화 여부)
`protocolVersion`	3.1 / 3.1.1 / 5.0 지원
`serverHost` / `serverPort`	Broker 주소 및 포트
`clientId` / `username` / `password`	클라이언트 식별자 및 인증 정보
`cleanSession` / `keepAliveInterval` / `connectTimeout`	세션 및 연결 매개변수

Edge-EMS Builder 장치 하나에 여러 MQTT 연결을 동시에 설정할 수 있습니다(예: 클라우드 플랫폼과 로컬 게이트웨이에 동시 연결). 발행/구독 설정은 각각 특정 연결에 바인딩됩니다.

2. 데이터 발행: 엣지 데이터를 임의 형식으로 조립하여 클라우드에 보고

발행 설정은 “얼마나 자주, 어떤 Topic으로, 어떤 내용을 보낼지”를 정의합니다.

매개변수	설명
`topic` / `qos`	발행 대상 및 서비스 품질 수준
`uploadStrategy`	발행 주기를 제어하는 CRON 표현식
`publishContent`	이번에 발행할 메시지 내용을 반환하는 Lua 스크립트

publishContent 스크립트는 표현식 엔진과 같은 문법을 사용하며 임의의 JSON 구조를 자유롭게 조립할 수 있습니다.

local payload = {}
payload.time = OffsetDateTime.now():unixMilli()
payload.power = ${PCS1_有功功率}
payload.status = ${PCS1_status}

-- 배열 필드도 지원합니다.
payload.phaseVoltages = { ${Meter1_Ua}, ${Meter1_Ub}, ${Meter1_Uc} }

return payload

엔진은 반환된 Lua Table을 JSON으로 자동 직렬화하여 지정 Topic에 발행하므로, 클라우드는 표준 JSON 메시지를 받습니다.

{
  "time": 1745393449910,
  "power": 15.2,
  "status": "Charging",
  "phaseVoltages": [220.1, 219.8, 220.5]
}

3. 메시지 구독: 클라우드 명령을 로컬 쓰기 동작으로 파싱

구독 설정은 “어떤 Topic을 구독하고, 메시지를 받으면 어떻게 처리하며, 응답할지”를 정의합니다.

매개변수	설명
`topic` / `qos`	구독 Topic 및 서비스 품질 수준
`actionContent`	수신 메시지를 파싱하고 쓰기 명령 목록을 반환하는 Lua 스크립트
`needResponse` / `responseTopic` / `response`	응답 필요 여부, 응답 Topic 및 응답 내용(스크립트 조립 지원)

구독 메시지를 수신하면 스크립트는 고정 변수 ${subscribe_message}로 원본 메시지를 가져와 파싱하고 쓰기 명령으로 변환할 수 있습니다.

local messageMap = jsonToMap(${subscribe_message})
local strategyList = jsonToListMap(toJsonString(messageMap.params.strategy))
local resultList = {}

for i, item in ipairs(strategyList) do
    local availableDate = completeDateTime(messageMap.params.date .. "T" .. item.start)
    local expiredDate = completeDateTime(messageMap.params.date .. "T" .. item["end"])

    table.insert(resultList, buildCommonWriteMap(
        "Customization", "mode", tostring(item.mode), availableDate, expiredDate, false
    ))
end

return resultList

이 스크립트는 클라우드가 전달한 “시간대별 전략”(여러 시간대와 각 시간대의 모드 값을 포함하는 JSON)을 여러 시간대별 데이터(Customization) 쓰기 명령으로 파싱합니다. 클라우드가 약속한 형식으로 JSON을 한 번 전달하면 엣지에서 시간대별로 자동 적용되므로 추가 개발이 필요하지 않습니다.

4. 응답이 필요한 경우

일부 클라우드 프로토콜(예: JSON-RPC 방식)은 메시지 전달 후 실행 결과 응답을 요구합니다. Edge-EMS Builder는 구독 설정에서 다음을 함께 정의할 수 있습니다.

responseTopic: 응답을 보낼 Topic입니다. 스크립트에서 원본 메시지의 id 등의 필드를 추출하여 동적으로 조합할 수 있습니다.
response: 응답 내용입니다. 고정 변수 ${subscribe_result}(동작 실행 성공 여부) 및 ${subscribe_result_message}(상세 실행 결과)를 참조할 수 있습니다.

따라서 클라우드는 전략을 보낸 후 단순히 “전송했으니 성공”이라고 가정하는 대신 엣지에서 실제로 적용되었는지 확인할 수 있습니다.

5. 대표 폐루프 예제

클라우드가 시간대별 전략 전달 → MQTT 구독 동작이 메시지 파싱 → 시간대별 데이터 쓰기(시간대에 따라 적용) → 트리거 구성이나 프런트엔드가 전략에 따라 실행 → 엣지가 발행 전략에 따라 실행 결과를 클라우드로 정기 반환

이는 가장 일반적인 클라우드와 엣지 협업 방식입니다. 전략 전달과 결과 보고를 서로 독립적으로 설정하므로 한쪽을 조정해도 다른 쪽에 영향을 주지 않습니다.

6. 연결 복구 후 전송 재개

장치가 일시적으로 네트워크에 연결되지 않아 발행 작업이 실패하면 Edge-EMS Builder는 실패한 메시지를 자동 캐시합니다(캐시 큐 크기 설정 가능). 연결이 복구되면 자동 재전송하여 네트워크 불안정으로 중요한 보고 데이터가 유실되지 않도록 합니다.

클라우드가 MQTT로 Edge-EMS Builder와 전략, 실행 상태 및 결과를 교환하는 흐름

이 그림은 본 페이지의 설정 로직을 바탕으로 데이터 및 제어 흐름을 보여 줍니다. 구체적인 작업 필드는 본문의 설정과 스크립트를 참조하세요.

다음 단계

발행/구독 스크립트의 전체 매개변수 및 요청·응답 메시지 형식: MQTT 발행/구독 스크립트 설명서
장치와 클라우드가 아닌 장치 간 직접 협업 방식: 장치 협업 및 공유 대상
Edge-EMS Builder는 클라우드뿐 아니라 자체 프런트엔드 화면에도 데이터를 실시간 전송할 수 있습니다. 프런트엔드 실시간 전송 및 직접 제어