SRS JSON Protocol Reference

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

1. 개요

1.1 목적

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

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

1.2 용어 및 약어(Abbreviations) 정의

용어/약어	정의
JSON	JavaScript Object Notation
UI	User Interface

---

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)를 사용한다.

Type	Description
REQ	요청 메시지 (Request)
RESP	응답 메시지 (Response)
NOTI	알림 메시지 (Notification) * one-way (no need reply)

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

Parameter	Type	Description
cmd	string	"SensingResult"
type	string	"NOTI"
payload	object
presence	Boolean	재실 감지 상태. 감지:true, 미감지:false
distance	Numeric	감지된 거리 (unit: cm)
power	Numeric	reflected power (unit: dB)
doppler	Numeric	단위시간동안 이동거리(unit: cm/s)

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

Parameter	Type	Required	Description
cmd	string	Y	"ModuleInfo"
type	string	Y	"REQ"

3.2.2 Response

Parameter	Type	Required	Description
cmd	string	Y	"ModuleInfo"
type	string	Y	"RESP"
payload	object	Y
model	string	Y	Model name of module
version	object	Y	version group
hw	string	Y	hardware version
sw	string	Y	software version

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

Parameter	Type	Required	Description
cmd	string	Y	"RadarConfig"
type	string	Y	"REQ"

Parameter	Type	Required	Description
cmd	string	Y	"RadarConfig"
type	string	Y	"RESP"
payload	object	Y
antennas	object	Y	Antenna object
tx	Numeric	Y	Number of transmission antennas
rx	Numeric	Y	Number of receiving antennas
gain	object	Y	gain object
tx	Numeric	Y	Transmit Antenna Gain (dB)
rx	Numeric	Y	Receive Antenna Gain (dB)
frequence	object	Y
start_freq	Numeric	Y	Start Frequency (GHz)
max_bandwidth	Numeric	Y	Maximum Bandwidth (MHz)
tx_power	Numeric	N	Transmit Power (dBm)
range	object	Y
maximum_range	Numeric	Y	Maximum Range (meteric)
bin_resolution	Numeric	Y	Range Bin Resolution (meteric)

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)

Parameter	Type	Required	Description
cmd	string	Y	"SetMaxRange"
type	string	Y	"REQ"
payload	object	Y
value	Numeric	Y	Max range (meteric)

3.4.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"SetMaxRange"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

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

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

3.5.1 Request (UI -> Module)

Parameter	Type	Required	Description
cmd	string	Y	"SetMacroThreshold"
type	string	Y	"REQ"
payload	object	Y
value	Numeric	Y	Sets macro threshold for presence algorithm. Range <0.01-2.0>

3.5.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"SetMacroThreshold"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

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

3.6.1 Request (UI -> Module)

Parameter	Type	Required	Description
cmd	string	Y	"SetMicroThreshold"
type	string	Y	"REQ"
payload	object	Y
value	Numeric	Y	Sets micro threshold for presence algorithm. Range <0.2-50.0>

3.6.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"SetMicroThreshold"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

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

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

3.7.1 Request (UI -> Module)

Parameter	Type	Required	Description
cmd	string	Y	"set_bandpass_filter"
type	string	Y	"REQ"
payload	object	Y
value	Numeric	Y	disable: 0, enable: 1

3.7.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"set_bandpass_filter"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

3.8 LQC모드(TBD)

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

3.8.1 Request (UI -> Module)

Parameter	Type	Required	Description
cmd	string	Y	"set_lqc_mode"
type	string	Y	"REQ"
payload	object	Y
value	Numeric	Y	on: 1, off: 0

3.8.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"set_lqc_mode"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

3.9 Rawdata Stream On/Off

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

3.9.1 Request (UI -> Module)

Parameter	Type	Required	Description
cmd	string	Y	"rawdata_stream"
type	string	Y	"REQ"
payload	object	Y
value	Numeric	Y	on: 1, off: 0

3.9.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"rawdata_stream"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

3.10 Rawdata Stream

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

3.10.1 Notification

Parameter	Type	Description
cmd	string	"RawData"
type	string	"NOTI"
payload	object
values	array	4-bytes Floating Point

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)

Parameter	Type	Required	Description
cmd	string	Y	"bindata_stream"
type	string	Y	"REQ"
payload	object	Y
value	Numeric	Y	on: 1, off: 0

3.11.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"bindata_stream"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

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

Parameter	Type	Description
cmd	string	"MacroBinValueMaxOrg" "MacroBinValueMaxFactor" "MicroBinValueMaxOrg" "MicroBinValueMaxFactor"
type	string	"NOTI"
payload	object
values	array	4-bytes Floating Point

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)

Parameter	Type	Required	Description
cmd	string	Y	"read_all_registers"
type	string	Y	"REQ"

3.13.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"read_all_registers"
type	string	Y	"RESP"
payload	object	Y
values	string	Y	register value (HexString) eg. ["0x25000033", "0x210000F3", ...]

3.14 Write All Radar Registers

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

3.14.1 Request (UI -> Module)

Parameter	Type	Required	Description
cmd	string	Y	"write_all_registers"
type	string	Y	"REQ"
payload	object	Y
values	array	Y	register value (HexString) eg. ["0x25000033", "0x210000F3", ...]

3.14.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"write_all_registers"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

3.15 Read Radar Register

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

3.15.1 Request (UI -> Module)

Parameter	Type	Required	Description
cmd	string	Y	"read_register"
type	string	Y	"REQ"
payload	object	Y
address	Numeric	Y	register offset address *Only the upper 7 bits are valid. eg. 24hex -> 36dec

3.15.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"read_register"
type	string	Y	"RESP"
payload	object	Y
value	string	Y	register value (HexString) eg. "0x25000033"

3.16 Write Radar Registers

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

3.16.1 Request (UI -> Module)

Parameter	Type	Required	Description
cmd	string	Y	"write_register"
type	string	Y	"REQ"
payload	object	Y
value	string	Y	register value (HexString) eg. "0x25000033"

3.16.2 Response (Module -> UI)

Parameter	Type	Required	Description
cmd	string	Y	"write_register"
type	string	Y	"RESP"
payload	object	Y
result	Numeric	Y	0(zero) on success, other codes on failure.

3.16.3 Example

• Request (UI -> Module)

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