← Docs hub

IoTAgent ↔ AWS IoT Core 토픽 명세

Sample 설계 참고 자료: 아래 토픽·메시지·운영 제안은 제품 확정 규격으로 강제하지 않는다. APP·Backend·IoTAgent 연결은 SoC와 APP·Backend 담당이 협의한다. 직접 맞출 기기 경계는 담당별 구현 범위와 두 구현 요청서를 따른다.

제품 연동 보강: 서버 저장 ACK와 완료 판정, 재전송·재부팅·시계 오차, 삭제 중 오프라인·늦은 commit, 인증서·기기 권한, 왕복 시험표. 제안 규칙의 삭제·동의 통지용 신규 토픽·필드는 아직 제품 계약 확정 전이며 이 문서가 가상의 wire 이름을 정의하지 않는다.

09-17 관심사 변경: App 저장은 서버 HTTPS로 처리한다. AI-Agent의 getVoicePersonalization은 IoTAgent가 request/voicePersonalization/{requestId}로 발행하고, 서버 결과는 기존 command/voiceProfileEnrollment의 action=personalizationResult로 수신한다. 전체 신규 규격·예제·그림. 현재 송신 구현은 샘플 MQTT이며 AWS 제품 연결은 별도다. 아래 interestsSet/interestsGet과 그 성공 예제는 중단된 로컬 규격이다.

화자 등록·조회·삭제와 화자별 관심사을 주고받는 MQTT 규격이다. 기존 코드의 수신 형식은 유지하고, 아직 연결되지 않은 제품 송신·저장 완료 경로는 별도로 표시한다.

1. 누가 보내고 받는가

IoT Core는 등록 결과를 판단하는 주체가 아니다. PUBLISH는 보내기, SUBSCRIBE는 해당 주소의 메시지를 받도록 등록하기다. 모바일과 등록 App은 MQTT에 직접 연결하지 않는다.

구조도 크게 보기

2. 구현 상태

현재 소스는 AWS 전체 연동 완료를 뜻하지 않는다. 이 문서 작업에서 앱 코드·기기 설정은 변경하지 않았다.

3. 토픽 목록

{deviceId}는 IoTAgent의 serialId와 동일한 기기 식별자다. {apiVersion}은 apiVersion/mUtil.getVersion()에서 오는 토픽 버전이며 아래 예제는 v1이다. JSON의 contractVersion과는 별개다.

Backend의 기기별 응답 구독 필터는 skmg/airbot/{deviceId}/v1/response/voiceProfileEnrollment/+다. +는 요청 ID 한 구간을 받기 위한 구독 필터이며 발행 주소에 넣지 않는다.

등록·삭제 명령은 action, 결과는 method로 구분한다. 관심사는 위 신규 조회 토픽을 사용한다. 기존 그림의 별도 event 토픽이나 syncAck는 현행 구현 명령이 아니다.

제품 발신 규칙: requestId는 UUID처럼 영문·숫자·하이픈·밑줄로 구성하고 /, +, #를 금지한다. 현재 IoTAgent 검사는 비어 있음/128자 초과만 확인하므로 토픽 안전 문자 검증은 추가 보완이 필요하다.

4. 명령 공통 형식

{
  "action": "start",
  "payload": {
    "contractVersion": "voice-profile-v2",
    "method": "startVoiceProfileEnrollment",
    "requestId": "vp-example-001",
    "nickname": "Niky",
    "locale": "ko-KR",
    "personalizationEnabled": true,
    "issuedAtMs": 0,
    "expiresAtMs": 0
  }
}

위 시각 0은 설명용이다. 송신할 때 현재 Unix 밀리초와 미래 만료 시각으로 바꾼다. 0 그대로는 만료 거절된다. 이 메시지가 수신되어도 바로 녹음하지 않고 등록 App을 연 뒤 사용자가 시작한다.

기기 주소는 토픽으로 선택한다. payload의 deviceId만으로 다른 기기를 선택하지 않는다. 제품 Backend는 발행 전에 계정의 기기 접근 권한을 확인해야 한다.

5. 작업별 입력과 결과

모든 작업은 4절 공통 필드를 보낸다. 아래 표는 추가 입력이다. 버전 P는 voice-profile-v2, M은 voice-memory-v1이다.

발음 보조 값은 MQTT 필드가 아니다.

관심사 코드: 실제 허용 목록

송신값은 아래 대문자 코드다. 표시 이름을 대신 보내지 않는다. 목록은 AI-Agent VoiceMemoryStore.ALLOWED_INTEREST_CODES 기준이다.

interestsSet은 추가 명령이 아니라 전체 목록 교체다. []는 모두 해제한다. 송신 측은 중복 없는 배열을 보낸다. 최대 16개는 배열 상한이고 현재 정의된 서로 다른 코드는 10개다. 허용 목록 밖 코드의 Service 검증 거절은 현재 무응답이 될 수 있으며, 전용 MQTT 오류 코드가 구현되어 있지는 않다.

조회·삭제·관심사 예제

{
  "action": "list",
  "payload": {
    "contractVersion": "voice-profile-v2",
    "method": "listVoiceProfiles",
    "requestId": "list-001",
    "issuedAtMs": 0,
    "expiresAtMs": 0
  }
}

{
  "action": "delete",
  "payload": {
    "contractVersion": "voice-profile-v2",
    "method": "deleteVoiceProfile",
    "requestId": "delete-001",
    "voiceId": "vp-example-001",
    "issuedAtMs": 0,
    "expiresAtMs": 0
  }
}

{
  "action": "interestsSet",
  "payload": {
    "contractVersion": "voice-memory-v1",
    "method": "setVoiceProfileInterests",
    "requestId": "interests-001",
    "voiceId": "vp-example-001",
    "interestCodes": [
      "WEATHER"
    ],
    "issuedAtMs": 0,
    "expiresAtMs": 0
  }
}

관리 요청마다 새 requestId를 사용한다. 취소만 대상 등록의 requestId를 재사용한다. 기록/관심사/삭제의 voiceId는 반드시 기기 목록에서 받은 실제 값으로 지정한다.

6. 응답 공통 형식

전송 확인과 업무 결과의 구분

MQTT에는 HTTP의 200/400 같은 업무 상태 코드가 없다. success, state, reasonCode는 MQTT가 아니라 이 애플리케이션 계약의 필드다. 현재 내부 Binder 오류는 로그만 남기고 MQTT 결과 없이 끝날 수 있다.

응답은 action/payload로 감싸지 않는 최상위 JSON이다. requestId는 토픽 마지막 구간과 본문이 같아야 한다.

{
  "contractVersion": "voice-profile-v2",
  "method": "voiceProfileListResult",
  "requestId": "list-001",
  "success": true,
  "reasonCode": "",
  "profiles": [
    {
      "voiceId": "vp-example-001",
      "nickname": "Niky"
    }
  ]
}

현재 Bridge는 success가 없는 Bundle에도 false를 삽입한다. 등록 상태 Bundle에는 원래 success가 없으므로 COMPLETED라도 MQTT JSON의 success=false일 수 있다. Backend는 method가 상태 이벤트면 state/terminal/voiceId로 판정해야 한다.

실패 시 추가 성공 필드는 없을 수 있다. method/requestId와 success 또는 state를 먼저 확인한다. Binder 필드별 원본은 전체 함수·Bundle 명세를 기준으로 한다.

요청별 완료 판정과 현재 오류 값

아래 reasonCode는 현재 Service 코드의 관리 결과 값이다. 네트워크에서 항상 전달된다는 보장이 아니며, 수신 검증에서 거절되면 결과 자체가 없을 수 있다.

예시: 조회·삭제 왕복

설명용 기기 ID를 DEVICE001로 둔다. 실제 발행 시 해당 기기의 serialId로 바꾼다.

AWS Backend PUBLISH
  skmg/airbot/DEVICE001/v1/command/voiceProfileEnrollment
  action=list, payload.requestId=list-001
      ↓ IoT Core → IoTAgent → DeviceAgent → AI-Agent
AI-Agent: 기기에 저장된 프로필 조회
      ↓ DeviceAgent → IoTAgent
IoTAgent PUBLISH (제품 AWS 송신 연결은 구현 필요)
  skmg/airbot/DEVICE001/v1/response/voiceProfileEnrollment/list-001
  method=voiceProfileListResult, requestId=list-001
      ↓ IoT Core → AWS Backend → 모바일 App 목록 갱신

삭제 요청의 requestId가 delete-001이면 결과 토픽도 /delete-001로 끝난다. 아래는 삭제 성공·실패 본문의 각 예시다.

{
  "contractVersion": "voice-profile-v2",
  "method": "voiceProfileDeleteResult",
  "requestId": "delete-001",
  "success": true,
  "voiceId": "vp-example-001",
  "reasonCode": ""
}

{
  "contractVersion": "voice-profile-v2",
  "method": "voiceProfileDeleteResult",
  "requestId": "delete-001",
  "success": false,
  "voiceId": "vp-example-001",
  "reasonCode": "ENROLLMENT_ACTIVE"
}

두 예시는 서로 다른 결과다. 실패이면 목록에서 먼저 삭제하지 않고 기존 표시를 유지한다. 성공도 Cloud 사본까지 삭제됐다는 의미는 아니다.

7. 등록 상태 이벤트

상태값별 의미

등록 상태는 AI-Agent가 만든 뒤 DeviceAgent가 등록 App(대상 번호 8)과 IoTAgent(대상 번호 2)에 복사 전달한다. 이 번호는 토픽 구간이나 JSON 필드가 아니다. 기기 내부 상태 분배 예시.

{
  "contractVersion": "voice-profile-v2",
  "method": "voiceProfileStateChanged",
  "requestId": "vp-example-001",
  "success": false,
  "state": "RECORDING_SET",
  "stateSequence": 2,
  "setIndex": 1,
  "setCount": 5,
  "progress": 20,
  "terminal": false,
  "nickname": "Niky",
  "reasonCode": ""
}

8. 오류·중복·연결 복구

MQTT PUBACK는 Broker 전달 확인이고 등록 완료·Cloud 저장 확인이 아니다. AWS는 QoS 0/1을 지원하며 QoS 1에는 재전달이 있으므로 중복 실행 방지가 필요하다. AWS MQTT

권장 Retain=false로 이전 등록/삭제 명령이 나중에 재실행되는 것을 피한다. expiresAtMs도 반드시 전송한다. 시험 Bridge의 cleanSession=true·메모리 저장·자동 재연결은 제품의 오프라인 결과 보관을 대신하지 못한다. timeout만으로 실패한 작업을 다시 start하지 말고 상태/목록을 확인한다.

9. 임베딩 업로드와 Cloud ACK

등록 임베딩은 Cloud로 보내야 한다. 다만 현재 commitVoiceProfile은 Binder 메서드이며 MQTT 명령이 아니다.

현재 경로는 AI-Agent → DeviceAgent 암호화 대기 저장이다. LOCAL_TEST_ACK는 로컬 시험 완료이고, WAITING_CLOUD_SYNC는 Cloud 미연결이다. 기존 MQTT Bridge에 임베딩 배열을 넣어도 제품 저장이 구현되지 않는다.

AWS MQTT payload 한도는 128 KB다. 제품 인코딩 이후 크기를 검사하고 초과 시 별도 업로드 방식이나 분할 계약을 먼저 정의한다. AWS MQTT 크기 제한

원본 PCM/WAV와 인식용 Query Embedding은 업로드하지 않는다. 명령 입력의 audio/pcm/wav/embedding/referenceEmbedding 필드는 현재 거절된다. 등록 임베딩의 상향 전송과 명령 입력 금지를 혼동하지 않는다.

10. AWS 설정과 책임

기기 인증서는 자기 기기 범위만 허용한다. iot:Subscribe는 topicfilter ARN, iot:Receive와 iot:Publish는 topic ARN을 사용한다. MQTT의 +/#와 IAM 정책의 */?는 다른 문법이다. AWS 발행·구독 정책

Backend는 MQTT 구독 프로세스 또는 IoT Rule→처리 서비스 중 하나를 주 수신 경로로 선택한다. 둘 다 사용하면 중복 저장을 방지해야 한다. 모바일에 기기 인증서나 MQTT 비밀값을 넣지 않는다.

11. 인수 시험

시나리오별 요청·결과 예시

아래는 메시지 형식 설명용이며 실제 AWS 시험 로그가 아니다. 모든 요청은 Backend가 skmg/airbot/DEVICE001/v1/command/voiceProfileEnrollment에 발행한다. 기기 ID와 voiceId는 실제 값으로 바꾼다. 시각 0은 실행 전에 issuedAtMs=현재 Unix 밀리초, expiresAtMs=issuedAtMs+60000으로 바꾼다. 60초는 예시 유효기간이며 서버에 고정된 기본값이 아니다.

결과는 IoTAgent가 skmg/airbot/DEVICE001/v1/response/voiceProfileEnrollment/{requestId}로 발행하는 형태다. 현재 제품 AWS publish 연결은 구현 대상이며 로컬 Bridge 형식을 기준으로 설명한다.

A. 등록 요청 → 기기에서 녹음 시작

Backend 발행:

{
  "action": "start",
  "payload": {
    "contractVersion": "voice-profile-v2",
    "method": "startVoiceProfileEnrollment",
    "requestId": "register-001",
    "nickname": "Niky",
    "locale": "ko-KR",
    "personalizationEnabled": true,
    "issuedAtMs": 0,
    "expiresAtMs": 0
  }
}

이 요청은 기기 등록 화면을 연다. 사용자가 시작 버튼을 눌러 녹음을 시작하면 /register-001에서 다음 상태를 받는다.

{
  "contractVersion": "voice-profile-v2",
  "method": "voiceProfileStateChanged",
  "requestId": "register-001",
  "success": false,
  "state": "RECORDING_SET",
  "stateSequence": 2,
  "setIndex": 1,
  "setCount": 5,
  "progress": 0,
  "terminal": false,
  "nickname": "Niky",
  "reasonCode": ""
}

모바일은 등록 진행 중으로 표시한다. 이 상태의 success=false는 시험 Bridge가 추가한 값이며 녹음 실패를 뜻하지 않는다. 아직 voiceId가 없을 수 있다.

B. 등록 취소 → 취소 상태

진행 중인 등록과 같은 requestId를 보낸다.

{
  "action": "cancel",
  "payload": {
    "contractVersion": "voice-profile-v2",
    "method": "cancelVoiceProfileEnrollment",
    "requestId": "register-001",
    "reason": "MOBILE_CANCELLED",
    "issuedAtMs": 0,
    "expiresAtMs": 0
  }
}

대상 세션에서 취소가 처리된 경우 /register-001의 결과:

{
  "contractVersion": "voice-profile-v2",
  "method": "voiceProfileStateChanged",
  "requestId": "register-001",
  "success": false,
  "state": "CANCELLED",
  "stateSequence": 3,
  "setIndex": 1,
  "setCount": 5,
  "progress": 0,
  "terminal": true,
  "nickname": "Niky",
  "reasonCode": "USER_CANCELLED"
}

모바일은 해당 등록의 진행 표시를 종료한다. reason 입력과 결과 reasonCode는 서로 다른 필드다. 세션 없음·ID 불일치·화면 실행 실패 시 현재는 결과가 오지 않을 수 있다.

C. 관심사 저장 → 저장된 목록 확인

아래는 이전 MQTT 저장 예제다. 현재 모바일 저장은 서버 HTTPS PUT이며 기기로 전송하지 않는다.

{
  "action": "interestsSet",
  "payload": {
    "contractVersion": "voice-memory-v1",
    "method": "setVoiceProfileInterests",
    "requestId": "interests-save-001",
    "voiceId": "vp-example-001",
    "interestCodes": [
      "WEATHER",
      "HEALTH"
    ],
    "issuedAtMs": 0,
    "expiresAtMs": 0
  }
}

/interests-save-001의 성공 결과:

{
  "contractVersion": "voice-memory-v1",
  "method": "voiceProfileInterestsResult",
  "requestId": "interests-save-001",
  "success": true,
  "reasonCode": "",
  "voiceId": "vp-example-001",
  "interestCodes": [
    "WEATHER",
    "HEALTH"
  ]
}

모바일은 응답의 voiceId에 해당하는 관심사를 갱신한다. 기존 관심사에 추가하는 것이 아니라 위 목록으로 교체한다.

D. 관심사 조회 → 해당 화자 값 표시

아래는 이전 MQTT 조회 예제다. 현재 모바일 GET은 서버 DB를 읽고, AI-Agent 조회는 신규 getVoicePersonalization을 사용한다.

{
  "action": "interestsGet",
  "payload": {
    "contractVersion": "voice-memory-v1",
    "method": "getVoiceProfileInterests",
    "requestId": "interests-read-001",
    "voiceId": "vp-example-001",
    "issuedAtMs": 0,
    "expiresAtMs": 0
  }
}

/interests-read-001의 결과:

{
  "contractVersion": "voice-memory-v1",
  "method": "voiceProfileInterestsResult",
  "requestId": "interests-read-001",
  "success": true,
  "reasonCode": "",
  "voiceId": "vp-example-001",
  "interestCodes": [
    "WEATHER",
    "HEALTH"
  ]
}

저장과 조회의 결과 method는 동일하다. 어떤 요청의 결과인지는 requestId로 구분한다. 빈 목록 []도 성공 결과가 될 수 있다.

검증 목록

이 목록은 제품 완료 조건이며 실기기/AWS 시험 통과 보고서가 아니다.

구현 근거와 연결 문서

2026-09-15 작업본 기준: SoC speaker_identification HEAD e54419a, AI-Agent feature/cpu-speaker-recognition HEAD 091e52bc 및 미커밋 구현 포함.

• IoTAgent mqtt/VoiceProfileContract.java: action/method/키 상수.
• IoTAgent mqtt/topic/CmdTopic.java: handleVoiceProfileEnrollment, buildVoiceMemoryCommand.
• IoTAgent mqtt/VoiceProfileMqttTestBridge.java: commandTopic, responseTopic, publishResult, toJsonPayload.
• IoTAgent IotAgent.java: 관리/실시간 callback을 시험 Bridge에 전달하는 분기.
• AI-Agent service/VoiceProfileIpcContract.kt: 등록 상태 Bundle 생성.
• 전체 프로토콜과 시나리오
• DeviceAgent 함수·Bundle 명세
• 모바일·Backend HTTPS 명세