> For the complete documentation index, see [llms.txt](https://srs.gitbook.io/srs-json-protocol-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://srs.gitbook.io/srs-json-protocol-reference/srs-json-protocol-reference.md).

# SRS JSON Protocol Reference

Version: 1.0.2  Last-Modified: 21, Sep. 2026

## 1. 개요

### 1.1 목적

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

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

### 1.2 용어 및 약어(Abbreviations) 정의

<table><thead><tr><th width="270">용어/약어</th><th>정의</th></tr></thead><tbody><tr><td>JSON</td><td>JavaScript Object Notation</td></tr><tr><td>UI</td><td>User Interface</td></tr><tr><td></td><td></td></tr></tbody></table>

***

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

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

* 시작 문자열:&#x20;

```
<!@SRS>
```

* 종료 문자열:

```
<SRS@!>
```

## 2. API 프로토콜 형식

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

### 2.1 데이터 형식

[JSON ( JavaScript Object Notation )](https://www.json.org/json-ko.html)

### 2.2  기본 형식:

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

```json
{
   "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 | <p>알림  메시지 (Notification)<br>\* one-way (no need reply)</p> |

#### 2.2.3 메시지 페이로드 (payload)

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

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

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

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

## 3. API 메시지

### 3.1 센서 감지 결과

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

#### 3.1.1 Notification

<table><thead><tr><th width="215">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>cmd</td><td>string</td><td>"SensingResult"</td></tr><tr><td>type</td><td>string</td><td>"NOTI"</td></tr><tr><td>payload</td><td>object</td><td></td></tr><tr><td>presence</td><td>Boolean</td><td>재실 감지 상태. 감지:true, 미감지:false</td></tr><tr><td>distance</td><td>Numeric</td><td>감지된 거리 (unit: cm)</td></tr><tr><td>power</td><td>Numeric</td><td>reflected power (unit: dB)</td></tr><tr><td>doppler</td><td>Numeric</td><td>단위시간동안  이동거리(unit:  cm/s)</td></tr></tbody></table>

#### 3.1.2 Example

* Notification (Module -> UI)

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

### 3.2 모듈 상태 조회

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

#### 3.2.1 Request

<table><thead><tr><th width="237">Parameter</th><th width="92">Type</th><th width="109">Required</th><th>Description</th></tr></thead><tbody><tr><td>cmd</td><td>string</td><td>Y</td><td>"ModuleInfo"</td></tr><tr><td>type</td><td>string</td><td>Y</td><td>"REQ"</td></tr></tbody></table>

#### 3.2.2 Response

<table><thead><tr><th width="242">Parameter</th><th width="84">Type</th><th width="112">Required</th><th>Description</th></tr></thead><tbody><tr><td>cmd</td><td>string</td><td>Y</td><td>"ModuleInfo"</td></tr><tr><td>type</td><td>string</td><td>Y</td><td>"RESP"</td></tr><tr><td>payload</td><td>object</td><td>Y</td><td></td></tr><tr><td>model</td><td>string</td><td>Y</td><td>Model name of module</td></tr><tr><td>version</td><td>object</td><td>Y</td><td>version group</td></tr><tr><td>  hw</td><td>string</td><td>Y</td><td>hardware version</td></tr><tr><td>  sw</td><td>string</td><td>Y</td><td>software version</td></tr></tbody></table>

#### 3.2.3 Example

* Request (UI -> Module)

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

* Response (Module -> UI)

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