SRS JSON Protocol Reference

Version: 1.0.1 Last-Modified: 14, Mar. 2024

1. 개요

1.1 목적

이 문서의 목적은 다음과 같다.

이 문서는 스마트레이더시스템(이하 'SRS')에서 개발되는 Radar Module과 UI 사이에서 원활한 데이터 교환이 이루어 질 수 있도록 API연동에 관한 내용을 정의한다.

1.2 용어 및 약어(Abbreviations) 정의

용어/약어

정의

1.3 통신 환경에 따른 추가 제어 문자

원활한 데이터 송/수신을 위하여 데이터 손실에 취약한 UART 환경에서 JSON 메시지 시작(Prefix)과 끝( Suffix)에 아래 문자열을 추가하여 메시지를 구분한다.

시작 문자열:

<!@SRS>

종료 문자열:

<SRS@!>

2. API 프로토콜 형식

이 문서에서 사용하는 API의 형식은 다음과 같다.

2.1 데이터 형식

JSON ( JavaScript Object Notation )

2.2 기본 형식:

각 object의 key값은 소문자(little-case)로만 작성한다.
공통으로 사용되는 "cmd", "type"는 필수 항목이며, 뒤에 따르는 "payload" 항목은 메시지 타입과 요청/응답에 따라 포함 여부가 결정된다.

{
   "cmd":"command_name",
   "type":"type_of_message",
   "payload":{
      "key1":"foo",
      "key2":930516,
      "key3":true
   }
}

2.2.1 메시지 이름 (cmd)

메시지 이름은 모듈과 UI간 패킷을 구분하기 위하여 중복되지 않는 유일한 이름을 사용한다.

단, 아래의 경우 예외로 한다.

요청메시지(REQ)에 의한 응답메시지(RESP)는 양방향(Two-way)의 쌍(Pair)구조로 이루어진 메시지
알림메시지(NOTI)를 활성화 시키는 목적의 요청(REQ)/응답(RESP)와 이에 활성화된 알림메시지

2.2.2 메시지 유형 (type)

메시지 유형에는 요청(Request)와 응답(Response)를 구분하기 위하여 아래의 type를 정의한다.

메시지 유형 문자열은 모두 대문자(upper-case)를 사용한다.

2.2.3 메시지 페이로드 (payload)

페이로드에는 각 메시지에 필요한 데이터를 나열한다.

자료형은 json 형식이 지원하는 아래 5가지를 사용한다.

수(Number)
문자열(String)
참/거짓(Boolean)
배열(Array)
객체(Object)

오버헤드(over head)를 줄이기 위해 payload 하위 object의 depth는 최대 5개까지로 한다.

3. API 메시지

3.1 센서 감지 결과

Radar Module의 전원이 인가되어, 정상 작동이 가능한 상태가 되면, 아래의 레이더 센서 감지 결과를 1초주기마다 알림 메시지로 전달한다.

3.1.1 Notification

3.1.2 Example

Notification (Module -> UI)

{
   "cmd":"SensingResult",
   "type":"NOTI",
   "payload":{
      "presence":true,
      "distance":210.01,
      "power":12.0,
      "doppler":90.02
   }
}

3.2 모듈 상태 조회

Radar Module의 기본 정보와 조회 시점의 상태 값 등을 호출한다.

3.2.1 Request

3.2.2 Response

3.2.3 Example

Request (UI -> Module)

{
   "cmd":"ModuleInfo",
   "type":"REQ"
}

Response (Module -> UI)

{
   "cmd":"ModuleInfo",
   "type":"RESP",
   "payload":{
      "model":"RM60-LAC",
      "version":{
         "hw":"3.0.1",
         "sw":"1.0.0"
      }
   }
}

3.3 레이더 설정조회(TBD)

Radar Module의 Radar 설정 상태를 호출한다.

3.3.1 Request

3.3.3 Example

Request (UI -> Module)

{
   "cmd":"RadarConfig",
   "type":"REQ"
}

Response(Module -> UI)

{
   "cmd":"RadarConfig",
   "type":"RESP",
   "payload":{
      "antennas":{
         "tx":1,
         "rx":1
      },
      "gain":{
         "tx":10.0,
         "rx":10.0
      },
      "frequence":{
         "start_freq":61.0201,
         "max_bandwidth":460.5
      }
   }
}

3.4 최대 감지 거리 설정(TBD)

재실 감지 알고리즘의 최대 거리를 설정한다. 범위는 0.65m ~ 5.0m이다.

3.4.1 Request (UI -> Module)

3.4.2 Response (Module -> UI)

3.5 Macro 민감도(Sensitivity) 설정(TBD)

재실감지 여부는 샘플링된 반사파의 신호 세기가 임계값(Threshold) 설정에 따라 판단되며, 설정값이 높을 수록 민감도가 높아집니다.

3.5.1 Request (UI -> Module)

3.5.2 Response (Module -> UI)

3.6 Micro 민감도(Sensitivity) 설정(TBD)

3.6.1 Request (UI -> Module)

3.6.2 Response (Module -> UI)

3.7 대역 필터 (Band-pass filter) 설정(TBD)

대역필터(Band-pass filter)의 사용 유무를 설정합니다.

3.7.1 Request (UI -> Module)

3.7.2 Response (Module -> UI)

3.8 LQC모드(TBD)

LQC (Line Quality Control) 생산 및 품질 테스트에 필요한 LQC 모드로 진입하거나 해제합니다.

3.8.1 Request (UI -> Module)

3.8.2 Response (Module -> UI)

3.9 Rawdata Stream On/Off

Radar 센서로부터의 입력되는 Rawdata(ADC Normalization) Stream을 On/Off한다.

3.9.1 Request (UI -> Module)

3.9.2 Response (Module -> UI)

3.10 Rawdata Stream

Radar 센서로부터의 입력되는 Rawdata를 단위시간 마다 Stream한다. 3.9 Rawdata Stream On/Off 메시지로 활성화가 되어야 한다.

3.10.1 Notification

3.10.2 Example

Notification (Module -> UI)

{
   "cmd":"RawData",
   "type":"NOTI",
   "values":[
      0.123,
      0.124,
      0.1235,
      0.1234,
      0.1233,
      "..."
   ]
}

3.11 Range Bin Data Stream On/Off

계산된 Range Bin의 Macro/Micro Data Stream을 On/Off한다.

3.11.1 Request (UI -> Module)

3.11.2 Response (Module -> UI)

3.12 Range Bin Data Stream

계산된 Range Bin의 Macro/Micro Data Stream한다.

Macro/Micro bin data를 Origin값과 Factor적용된 값으로 총 4개의 메시지가 각각 NOTI 타입으로 전송된다.

3.11 Range Bin Data Stream On/Off 메시지로 활성화가 되어야 한다.

3.12.1 Notification

3.12.2 Example

Notification (Module -> UI)

{
   "cmd":"RawData",
   "type":"NOTI",
   "values":[
      0.123,
      0.124,
      0.1235,
      0.1234,
      0.1233,
      "..."
   ]
}

3.13 Read All Radar Registers

Radar 센서의 전체 레지스터(Register)의 값을 조회한다. *. BGT60UTRxxAiP 기준으로 레지스터 어드레스는 총 40개이다.

3.13.1 Request (UI -> Module)

3.13.2 Response (Module -> UI)

3.14 Write All Radar Registers

Radar 센서의 전체 레지스터(Register)의 값을 기록한다. *. BGT60UTRxxAiP 기준으로 레지스터 어드레스는 총 40개이다.

3.14.1 Request (UI -> Module)

3.14.2 Response (Module -> UI)

3.15 Read Radar Register

Radar 센서의 특정 레지스터(Register)의 값을 조회한다.

3.15.1 Request (UI -> Module)

3.15.2 Response (Module -> UI)

3.16 Write Radar Registers

Radar 센서의 전체 레지스터(Register)의 값을 기록한다.

3.16.1 Request (UI -> Module)

3.16.2 Response (Module -> UI)

3.16.3 Example

Request (UI -> Module)

{
   "cmd":"write_register",
   "type":"REQ",
   "payload":{
      "value":"0x25000032"
   }
}

Last updated 8 months ago