Smart[Fleet] 파트너 구축 가이드¶

Version	Last modified date
1.0	2017/11/28

Contents:

Smart[Fleet] 플랫폼 소개¶

Smart[Fleet] 플랫폼은 SK텔레콤(이하 SKT)에서 제공하는 커넥티드카 플랫폼으로 커넥티드카 솔루션을 개발하고자 파트너사들에게 보다 쉽고, 빠르고, 다양한 서비스를 안전하게 개발할 수 있는 다양한 기능들을 제공합니다.

Smart[Fleet] 플랫폼은 아래 그림과 같이 코어 엔진 부분에 차량 모니터링(Monitor), 경로 최적화(Route), 차량과 통신(V2X), 데이터 분석(Data), 교통정보 분석(Traffic) 등의 5개 차량 관제 핵심 기능을 제공합니다.

본 문서는 5개 핵심 기능들과 파트너사들의 장치들이 연동하기 기능개발 절차와 기술 규격에 대해서 정의하고 있습니다.

주요 특징¶

간편한 API 지원

Smart[Fleet] 플랫폼과 차량 내 센서들간 연동을 쉽게 개발할 수 있도록 간결하고, 다양한 API들을 제공하고 있습니다.

구분	설명
Simple API	차량 내 설치되는 센서들(예 : OBD-2, ADAS, GPT 센터 등)에게는 최소한의 API만을 제공하여 개발의 복잡도를 낮춰 드립니다. 이를 위해서 기존에 많이 사용되는 HTTP 프로토콜과 비교하여 저전력, 보다 빠른 데이터 처리, 가벼운 통신 규격을 지원하는 MQTT 프로토콜을 지원하고 있습니다.
Useful API	차량 운행기록, 차량배차 관리, 운전자 운행습관 분석 등과 같은 다양한 서비스를 간편하게 구현할 수 있습니다. 센서 연동 API를 통해서 차량 내 정보를 올려주면 Smart[Fleet] 플랫폼에서 복잡한 분석 절차를 처리하고 RESTful API를 통해 고객들에게 원하는 정보를 제공해드립니다.

유연한 커넥티드카 센서 연동 인터페이스 및 SDK 제공

커네티드 카 솔루션에서 차량 정보 수집 및 제어를 위해서 많이 사용되는 다양한 차량 내 센서들과 연동을 하기 위한 연동 규격을 제공합니다. 그리고 센서들의 품질관리와 보안을 보장하기 위하여 SKT에서는 Certification Program(링크 필요)을 운영합니다.

구분	설명
다양한 센서 연동 규격	OBD-2, ADAS, DTG 센서 또는 스마트폰을 통해서 차량을 관제할 수 있는 유연한 인터페이스를 제공합니다. Smart[Fleet] 프랫폼의 데이터 분석 기능을 활용하기 위해서는 SKT에서 제공하는 메시지 포맷 규약을 따라야 합니다.
SDK 제공	Smart[Fleet] 플랫폼과 센서간의 연동 기능 개발을 보다 쉽게 하실 수 있도록 다양한 언어의 SDK를 제공합니다. 또한 Starter Kit(링크) 솔루션을 활용하여 쉽게 단말 연동 기능 시험 및 프로토타입 솔루션을 기획하실 수 있습니다.

저전력 IoT 전용 네트워크 연결 지원

국내 1위 이동통신망 사업자인 SKT는 IoT 서비스에 최적화된 저전력 기반의 LPWAN(Low Power Wide Area Network) 통신 서비스를 제공하고 있습니다. 특히 커넥티드카 서비스의 핵심 중 하나는 끊김이 없고 안정적인 연결성 보장, 실시간 양방향 데이터 통신, 차량 내 센서 전원 특성을 고려한 저전력 소비 등을 보장하는 무선통신기술이 요구됩니다. 또한 합리적인 가격대의 다양한 무선통신 칩셋과 커넥티드카 전용통신요금도 필요합니다. 이런 특징들을 모두 보장할 수 있는 무선통신망 기술이 LPWAN이며, SKT는 LoRa, LTE-M, LTE-M1 등 국내에서 가장 많은 종류의 LPWAN 통신 서비스를 지원하고 있습니다.

SKT IoT 솔루션과 연동 지원

Smart[Fleet] 플랫폼의 또 하나의 장점은 시장에서 검증되고 범용화된 SKT의 다양한 IoT 솔루션들과 연동하여 보다 풍부한 커넥티드카 서비스를 구현할 수 있습니다. Smart[Fleet] 플랫폼은 SKT IoT 솔루션인 T map(네비게이션), ThingPlug(개방형 IoT 플랫폼), Smart[Home](스마트홈), 누구(AI 기반의 음성인식) 등과 연동 기능을 제공하고 있으므로 차량뿐만 아니라 보다 다양한 영역에서 활용이 가능한 서비스 시나리오들을 구성할 수 있습니다.

원스톱 서비스 지원

SKT는 커넥티드카 솔루션 및 서비스를 기획하는 파트너들의 사업 성공을 위해서 기획부터 기술개발, 서비스 런칭까지 원스톱 서비스를 지원합니다. 또한 사업 런칭 후에도 파트너들의 다양한 요구사항에 대한 전문적인 대응을 통하여 안정적으로 사업이 유지되도록 지원합니다.

제공 주요 기능¶

Smart[Fleet] 플랫폼은 파트너업체들이 커넥티드카 단말의 성능 시험이나 시장에서 경쟁력있는 커넥티드카 서비스 개발을 쉽게 할 수 있도록 Smart[Fleet] 포털 및 REST API 등을 통하여 다양한 기능을 제공합니다.

주요 구성요소 (Entity Architecture)¶

Smart[Fleet] 플랫폼은 커넥티드카 서비스 특성에 맞도록 설계된 유연한 데이터 구조를 지원합니다.

기본 구성요소 (Basic Entity)¶

구분	설명
Company	차량(vehicle)을 관리하는 업체(예: 렌터카 회사, 보험회사 등) 관리자 계정을 통해 차량을 등록 및 관리한다. 등록한 차량은 다른 company와 공유가 가능하다. 차량을 공유하는 경우 해당 차량을 공유받은 company도 차량 관리가 가능하다. 등록된 차량 및 공유된 차량을 director에게 할당한다. Company는 운영사(Master company)와 협력사(Partner company)로 구분된다. 운영사(Master) Smart[Fleet] 시스템 관리자에 의해서 등록된다. 차량을 등록할 수 있다. 협력사를 등록하고 수정, 삭제할 수 있다. (협력사가 등록한 협력사의 수정, 삭제도 가능) 등록한 차량을 선택적으로 협력사에 권한위임(delegate)할 수 있다. (위임 후 위임해지 가능) 협력사(Partner) Company 관리자에 의해서 등록된다. 차량을 등록할 수 있다. 협력사를 등록할 수 있다. (수정, 삭제 불가) 등록한 차량은 모두 운영사에 권한위임(delegate)된다. (자동으로 위임되며, 위임을 해지할 수 없다.) 등록한 차량을 선택적으로 협력사에 권함위임(delegate)할 수 있다. (위임 후 위임해지 가능)
Director	차량을 소유하고 있는 사용자 할당받은 차량에 대한 각종 정보를 확인할 수 있고, RPC 통신을 통해 차량을 제어할 수 있다. 차량의 운행 활성화/비활성화를 지정하여 Driver가 차량을 운행할 수 있도록 한다. Driver 역할도 수행할 수 있다.
Driver	차량을 운전하는 사용자 Director가 운행을 활성화한 차량 중 서비스레벨에서 운행 권한을 획득하여 차량을 운행한다. 운행만 가능하며 실제로 차량을 소유하지 못한다.
vehicle	차량 Company를 통해 등록되며 다른 company에 공유될 수 있다. 차량은 director에게 할당되며, 센서로부터 올라오는 데이터를 종합 관리한다.
Device (Sensor)	OBD, ADAS 등과 같은 센서 장치로 차량으로부터 필요한 데이터를 센싱하여 데이터를 플랫폼으로 전달하는 주체

부가 구성요소¶

각 구성요소는 차량을 기준으로 Owner(Company)와 Delegated Owner(Delegated company)로 구분되며, 본 절에서는 Delegated owner 구성요소에 대해서 설명합니다.

구성요소	개요
Delegated Company (위임 회사)	차량을 공유받은 업체 공유받은 차량을 delegated director에게 할당한다. 공유받은 업체는 해당 차량을 관리할 수 있으나 플랫폼에서 삭제할 수 없다.
Delegated Director (위임 디렉터)	공유된 차량에 대해 권한을 가진 사용자 할당받은 차량에 대한 각종 정보를 확인할 수 있고, RPC 통신을 통해 차량을 제어할 수 있다. 차량의 운행 활성화/비활성화를 정하여 (Delegated) Driver가 차량을 운행할 수 있도록 한다. 자신이 Driver의 역할을 수행하여 차량을 운행할 수 있다.
Delegated Driver (위임 운전자)	공유된 차량을 운전하는 사용자 Delegated Director가 운행을 활성화한 차량 중 서비스레벨에서 운행 권한을 획득하여 차량을 운행한다. 운행만 가능하며 실제로 차량을 할당받지는 않는다. ID, password로 로그인하며 허가받은 차량에 대해 운행하면 운행 기록에 해당 driver에 대해 저장된다. 운행이 종료된 후에는 다른 Driver의 운행이 가능하도록 로그아웃한다.

Note

부가 구성요소(Delegated Entity)가 적용되는 시나리오 예시 :

‘SK화재’(owner company)가 관리하는 차량 V1에 사고가 발생하여 ‘김출동’(Director)이 현장 출동
‘김출동’(Director)은 운전자’홍길동’(Driver)에게 차량을 인계받아 해당 차량 수리 의뢰를 위해서 ‘SK화재’ 위탁 수리업체인 ‘영진카센터’(Delegated company)로 차량 공유 요청함
‘SK화재’에서는 사고 차량을 ‘영진카센터’(Delegated company)에 공유
‘영진카센타’의 ‘차수리’(Director)는 차량을 수리하기 시작하고, 수리에 관한 정보는 ‘SK화재’에 공유됨
수리가 완료되고 차량을 운전자 ‘홍길동’에게 인계하기 위해 ‘차배달’(Delegated Driver)에게 차량을 인도함
‘차배달’(Delegated Driver)은 운전자 ‘홍길동’(Driver)에게 차량을 전달하고 전달 확인증을 ‘김출동’(Direcotr)에게 제출
‘김출동’(Director)은 ‘SK화재’에 요청하여 차량 V1에 대한 ‘영진카센터’와의 공유를 종료

서비스 세부 절차¶

Smart[Fleet] 플랫폼을 사용하려는 파트너들을 위한 매뉴얼입니다. 파트너의 유형 별 플랫폼 사용 절차에 대해 설명합니다.

전체 세부 절차¶

Smart[Fleet] 플랫폼을 이용하기 위한 절차는 다음과 같이 구성되어 있습니다.

위 절차들은 Smart[Fleet] 웹 포털 사이트 에 접속하거나 플랫폼에서 제공하는 Open API 를 이용하여 이용할 수 있습니다.

파트너별 이용 안내¶

Smart[Fleet] 파트너 유형은 크게 3가지로 구분합니다.

커넥티드카 서비스 사업자 : 차량을 이용하여 커넥티드카 사업을 하려고 하는 파트너
Device 개발자 : 차량 내 부착되는 Device를 개발하는 파트너
App 개발자 : Smart[Fleet] 플랫폼에서 제공하는 Open API를 활용하여 App을 개발하는 파트너

Smart[Fleet] 플랫폼을 이용하는 파트너 유형별로 아래 절차를 참고하셔서 본 파트너 매뉴얼을 활용하시면 보다 편리하게 이용하실 수 있습니다.

커넥티드카 서비스 사업자¶

사업 문의

Smart[Fleet] 포털 ‘Support/사업문의’ 메뉴를 통해서 커넥티드카 서비스 및 Smart[Fleet] 플랫폼 활용방안 등에 대해서 문의를 하실 수 있습니다. 등록된 문의는 SKT Smart[Fleet] 사업 컨설팅 전문가에게 전달되어 전문가의 컨설팅 서비스를 받으실 수 있습니다. 고객사와 함께 할 협력사를 모집하고, SKT 담당자를 통해 센서 등 단말제조업체 등을 소개받을 수 있습니다.

서비스 및 회사 등록

구체적인 사업 계획이 잡히고 SKT 담당자와의 협의가 완성되면 포털에서 서비스 등록을 신청합니다. 세부 절차는 4.1. 서비스 등록 절차 를 참고하시기 바랍니다.

협력사 등록

서비스 및 함께 사업을 할 협력회사를 등록합니다. 귀사로부터 귀사의 차량을 위임받을 수도 있고, 반대로 협력사의 차량을 위임받아서 귀사가 관리할 수 있습니다. 세부 절차는 4.2. 회사(협력사) 등록 절차 를 참고하시기 바랍니다.

차량 등록

커넥티드카 서비스 대상 차량을 등록합니다. 차량 내 각종 정보를 수집하기 위해서 부착되는 센서들이 차량 정보를 인식할 수 있도록 차량에 대한 자세한 정보를 입력합니다. 세부 절차는 4.3. 차량 등록 절차 를 참고하시기 바랍니다.

센서 등록

등록한 차량에 부착된, 또는 부착할 센서 장치 등을 등록합니다. 세부 절차는 4.4. 센서 등록 절차 를 참고하시기 바랍니다.

차량과 센서 연결

차량과 센서를 포털에 등록하면 Smart[Fleet] 플랫폼이 자동으로 차량과 센서간 연결을 제어하고, 차량으로부터 커넥티드카 서비스를 위한 각종 정보들을 수집하기 시작합니다.

디렉터 등록

등록된 차량이 다수이어서 소수의 관리자가 관리하기 어려울 경우에는 복수의 디렉터를 할당할 수 있습니다. 세부 절차는 4.5. 디렉터 등록 절차 를 참고하시기 바랍니다.

드라이버 등록

차량을 관리하지 않지만 실제 운전을 담당할 운전자를 드라이버로 등록할 수 있습니다. 세부 절차는 4.6. 운전자 등록 절차 를 참고하시기 바랍니다.

차량 위임

커넥티드카 서비스 모델에 따라서 고객사의 차량을 협력사(예: 보험회사 등)에 관리권한을 위임할 수 있습니다. 위임받은 협력사는 귀사의 차량을 관리할 수 있으며, 차량관리 정보는 귀사에게 보고됩니다. 세부 절차는 4.7. 위임회사 등록 절차 를 참고하시기 바랍니다.

Device 개발자¶

차량 내 부착되는 Device는 Smart[Fleet] platform과 MQTT프로토콜을 이용하여 통신합니다. MQTT에 대한 자세한 사항은 MQTT.org 를 참고하시기 바랍니다.

사전 준비 사항

Smart[Fleet] 플랫폼을 사용하려면 서비스와 회사가 먼저 등록되어야 합니다. 4.1. 서비스 등록 절차 , 4.2. 회사(협력사) 등록 절차 를 참고하여 Smart[Fleet] 플랫폼에 연결하는 방법을 확인시기 바랍니다.

Activation

Device에 따라 Activation이 필요할 수도 있습니다. Activation이 필요한 센서에 대해서는 4.3. 차량 등록 절차 절차 내용을 참고하시기 바랍니다.

메시지 전송

Smart[Fleet] 플랫폼과 연결이 완료되면 차량 내 부착된 센서들로부터 수집된 정보를 플랫폼으로 전송하기 시작합니다. 세부 절차는 4.4. 센서 등록 절차 절차를 참고하시기 바랍니다.

차량 내 센서가 Smart[Fleet] 플랫폼으로 센싱한 정보를 정상적으로 전송하기 위해서는 Smart[Fleet] 플랫폼에서 정의한 단말기 메시지 포맷을 맞추어야 합니다. 단말기 메시지 포맷 규격은 8. 메시지 포맷 내용을 참고하시기 바랍니다.

RPC

어플리케이션에서 센서로부터 특정 데이터를 요구하거나, 특정 행동을 요청할 경우에는 RPC를 사용합니다. RPC 이용 절차는 5.2. Sensor RPC 내용을 참고하시기 바랍니다.

SDK

마지막으로 SDK를 참고하여 개발을 하실 수 있습니다. ODB2나 ADAS와 같이 센서가 부착된 디바이스를 개발하는 개발자는 7.1. Embedded-C SDK 를 참고하시고, 스마트폰의 GPS를 사용하여 개발하는 개발자는 7.2 Android SDK , 7.3. Object-C(iOS) SDK 내용을 참고하시기 바랍니다.

App 개발자¶

Smart[Fleet] 에서 제공하는 포털을 사용하지 않을 경우 고객사에서 자체적으로 App을 제작할 수 있습니다. 자체 App 개발을 진행하는 경우에는 Smart[Fleet] 플랫폼에서 제공하는 Open API를 활용하여 커넥티드카 서비스 App을 보다 쉽게 개발할 수 있습니다.

구성 요소 등록

우선 Smart[Fleet] 구성 요소의 등록 방법은 4. 구성요소(Entity) 등록 절차를 통해서 자세하게 확인할 수 있습니다.

Open API

Smart[Fleet] 플랫폼은 Restful Open API를 제공합니다. API를 통해 Smart[Fleet] 플랫폼에 데이터를 만들고 조회할 수 있습니다. Open API 규격에 대해서는 6. API 규격 내용을 참고하시기 바랍니다.

메시지 포맷

차량에 부착된 센서들로부터 전송되는 자동차 운행과 관련된 정보의 메시지 포맷은 6. 단말기 메시지 포맷 내용을 참고하시기 바랍니다.

Web App을 개발하는 개발자는 7.2. Web Application Simulator 내용을 참고하시기 바랍니다.

구성요소(Entity) 등록¶

이 매뉴얼은 Smart[Fleet] 플랫폼을 사용하기 원하는 파트너들에게 플랫폼 사용을 위한 절차를 설명하기 위한 것입니다.

Device 와 플랫폼을 연동하는 방법은 5. Device 연동 절차 와 8. 메시지 포맷 을 참고하십시오. App 개발자는 6. API 규격 과 7. SDK 를 참고하십시오.

구성요소를 등록하는 방법은 2가지가 제공되고 있습니다.

Smart[Fleet] 포털 : Smart[Fleet] 플랫폼에서 제공하는 웹 서비스를 이용하는 방법
Smart[Fleet] API : Smart[Fleet] 플랫폼에서 제공하는 HTTP 기반 Rest API를 이용하는 방법

각 등록 절차마다 두 가지 방법이 설명되어 있으니 참고하시기 바랍니다.

서비스 등록 (Service Registration)¶

Smart[Fleet] 포털을 통한 등록¶

Smart[Fleet] 메인의 ‘서비스 등록’ 버튼을 통해 등록 신청 페이지로 이동합니다.

필수 항목을 작성하여 서비스 등록 신청을 하면 신청한 내용이 SKT담당자에게 전달되고 검토 결과는 입력한 이메일로 발송됩니다.

서비스 등록이 완료될 경우 운영사 계정이 자동으로 생성되며 ID는 입력한 이메일 주소와 동일합니다. 비밀번호는 등록완료 안내메일의 링크를 통해 설정이 가능합니다.

API를 활용한 등록¶

포털을 통해서 회사 계정을 받은 파트너사에게 Smart[Fleet] 플랫폼에 접근할 수 있는 JWT 토큰을 제공합니다. REST API를 통해서 정상적으로 등록한 서비스의 토큰을 확인하는 방법은 다음과 같습니다.

로그인 요청 정보 API¶

POST

/api/auth/login

Header

option	Type	Default	Description
Content-Type	string	application/json	content type

Body

Key	Type	Description
username	string	로그인할 아이디(이메일)
password	string	패스워드

Example Code

Request

content-type:"application/json"

{
    "username":"example@example.com",
    "password":"1234"
}

Response (code: 200)

{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…",
    "refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1…"
}

요청이 성공하면(code:200) Response에서 인증 토큰으로 사용할 token 필드를 얻을 수 있습니다. Token 필드는 HTTP Header에 “X-Authorization”의 값으로 사용되며 로그인할 때마다 변경됩니다. 토큰이 있으면 해당 계정에 접근할 수 있으므로 외부 유출이 안되도록 주의해야 합니다.
토큰을 얻었으면 회사 정보 등록 API를 통해 서비스를 등록합니다.
요청 파라미터를 입력할 때 ServiceType이 중복되지 않도록 해야 합니다. ServiceType은 Unique 값으로 하나의 ServiceType에 한 운영사만 등록할 수 있습니다.

회사 정보 등록 API¶

POST

/api/tre/v1/company

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Body

Key	Type	Description
name	string	등록할 회사 명칭
region	string	등록할 회사 지역
serviceType	string	운용하는 사업 명칭
picName	string	등록할 COMPANY_ADMIN 이름
picPhone	string	등록할 COMPANY_ADMIN 연락처
picEmail	string	등록할 COMPANY_ADMIN 이메일
picPasswd	string	등록할 COMPANY_ADMIN 패스워드
picDivision	string	등록할 COMPANY_ADMIN 소속 부서
sktManagerName	string	SKT 담당 매니저 이름
sktManagerEmail	string	SKT 담당 매니저 이메일
cooperationTask	string	협력사 정보, 협력사 업무에 대해 기술
description	string	추가 정보
rpcNotifyHost	string	RPC 결과를 전송받기 위한 서버 호스트
rpcNotifyPort	integer	RPC 결과를 전송받기 위한 서버 포트
rpcNotifyBasePath	string	RPC 결과를 전송받기 위한 서버 기본 경로

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "name":"운영사A",
    "region":"대한민국",
    "serviceType":"example",
    "picName":"김담당자",
    "picEmail":"companya@example.com",
    "picPhone":"010-0000-0000",
    "picPasswd":"1234",
    "picDivision":"사업1팀",
    "sktManagerName":"박매니저",
    "sktManagerEmail":"manager@skt.com",
    "cooperationTask":"수리",
    "description":"additional description",
    "rpcNotifyHost":"localhost",
    "rpcNotifyPort":9000,
    "rpcNotifyBasePath":"/rpc_noti"
}

Response (code: 200)

{
    "id": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509530124485,
    "name": "운영사A",
    "serviceType": "example",
    "master": true,
    "masterId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "picPasswd": "1234",
    "picName": "김담당자",
    "picPhone": "010-0000-0000",
    "picEmail": "companya@example.com",
    "picDivision": "사업1팀",
    "sktManagerName": "박매니저",
    "sktManagerEmail": "manager@skt.com",
    "cooperationTask": "수리",
    "description": "additional description",
    "rpcNotifyHost": "localhost",
    "rpcNotifyPort": 9000,
    "rpcNotifyBasePath": "/rpc_noti"
}

정상적으로 등록하면(code:200) 위와 같이 생성된 회사 정보를 Response 값으로 확인할 수 있습니다.

운영사는 master 필드가 true로 출력되므로 master 필드를 통해 이 회사가 운영사로 등록됐는지 구분할 수 있습니다. 생성한 회사 계정으로 처음 로그인할 때 입력한 picEmail를 아이디, picPasswd를 패스워드로 사용합니다. 예시로 보면 아이디는 “companya@example.com”, 패스워드는 “123가”입니다. 패스워드는 로그인 후에 변경할 수 있습니다.

REST API를 사용할 때 입력하는 Company ID는 Response 데이터에 있는 id 필드입니다. 예시에 있는 “c7fc12a0-beea-11e7-8bdf-af923035d741”이 Company ID입니다.

회사(협력사) 등록 (Company (Partner) Registration)¶

Smart[Fleet] 포털을 통한 등록¶

운영사 Admin 계정으로 로그인 후 ‘협력사’ 메뉴에서 등록 가능합니다.

협력사 리스트 페이지에서 등록버튼을 통해 등록 페이지 이동

필수 항목 입력

API를 활용한 등록¶

운영사 계정을 통해서 협력사를 생성할 수 있습니다. 협력사를 등록하기 전에 운영사 계정으로 로그인하여 토큰 데이터를 얻습니다. 4.1.2.2. 회사 정보 등록 API 와 비교하면 계정이 가진 권한에 차이가 있을 뿐 등록 절차는 동일합니다.

로그인 요청 정보 API¶

POST

/api/auth/login

Header

option	Type	Default	Description
Content-Type	string	application/json	content type

Body

Key	Type	Description
username	string	로그인할 아이디(이메일)
password	string	패스워드

Example Code

Request

    content-type:"application/json"

{
    "username":"companya@example.com",
    "password":"1234"
}

Response (code: 200)

{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…",
    "refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1…"
}

요청 파라미터를 입력할 때 협력사 ServiceType에는 운영사와 동일한 ServiceType을 기입합니다. 요청이 성공하면(code:200) Response에서 인증 토큰으로 사용할 token 필드를 얻을 수 있습니다. 토큰을 얻었으면 회사 정보 등록 API를 통해 서비스를 등록합니다.

회사 정보 등록 API¶

POST

api/tre/v1/company

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string	application/json	auth token

Body

Key	Type	Description
name	string	등록할 회사 명칭
region	string	등록할 회사 지역
serviceType	string	운용하는 사업 명칭
picName	string	등록할 COMPANY_ADMIN 이름
picPhone	string	등록할 COMPANY_ADMIN 연락처
picEmail	string	등록할 COMPANY_ADMIN 이메일
picPasswd	string	등록할 COMPANY_ADMIN 패스워드
picDivision	string	등록할 COMPANY_ADMIN 소속 부서
sktManagerName	string	SKT 담당 매니저 이름
sktManagerEmail	string	SKT 담당 매니저 이메일
cooperationTask	string	협력사 정보, 협력사 업무에 대해 기술
description	string	추가 정보
rpcNotifyHost	string	RPC 결과를 전송받기 위한 서버 호스트
rpcNotifyPort	integer	RPC 결과를 전송받기 위한 서버 포트
rpcNotifyBasePath	string	RPC 결과를 전송받기 위한 서버 기본 경로

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "name":"협력사B",
    "region":"대한민국",
    "serviceType":"example",
    "picName":"김담당자",
    "picEmail":"companyb@example.com",
    "picPhone":"010-0000-0000",
    "picPasswd":"1234",
    "picDivision":"사업1팀",
    "sktManagerName":"박매니저",
    "sktManagerEmail":"manager@skt.com",
    "cooperationTask":"수리",
    "description":"additional description",
    "rpcNotifyHost":"localhost",
    "rpcNotifyPort":9000,
    "rpcNotifyBasePath":"/rpc_noti"
}

Response (code: 200)

{
    "id": {
        "id": "3820ea50-beec-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509530742131,
    "name": "협력사A",
    "serviceType": "example",
    "master": false,
    "masterId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "picPasswd": "1234",
    "picName": "김담당자",
    "picPhone": "010-0000-1111",
    "picEmail": "companya@example.com",
    "picDivision": "사업1팀",
    "sktManagerName": "박매니저",
    "sktManagerEmail": "manager@skt.com",
    "cooperationTask": "수리",
    "description": "additional description",
    "rpcNotifyHost": "localhost",
    "rpcNotifyPort": 9000,
    "rpcNotifyBasePath": "/rpc_noti"
}

정상적으로 등록하면(code:200) 위와 같이 생성된 회사 정보를 Response 값으로 확인할 수 있습니다.

협력사는 Master 필드가 False로 출력되므로 Master 필드를 통해 이 회사가 협력사로 등록됐는지 구분할 수 있습니다. 생성한 회사 계정으로 처음 로그인할 때 입력한 picEmail를 아이디로, picPasswd를 패스워드로 사용합니다. 예시로 보면 아이디는 “companyb@example.com”, 패스워드는 “1234”입니다. 패스워드는 변경할 수 있습니다.

REST API를 사용할 때 입력하는 Company ID는 Response 데이터에 있는 id입니다. 예시에 있는 “3820ea50-beec-11e7-8bdf-af923035d741”이 Company ID입니다.

차량 등록 (Vehicle Registration)¶

Smart[Fleet] 포털을 통한 등록¶

서비스에 사용할 차량을 등록하는 단계이며, 차량메뉴에서 등록이 가능합니다.

차량 리스트 페이지에서 등록 버튼을 통해 등록 페이지로 이동합니다.

차량 등록 시 1대씩 등록하거나 파일을 이용하여 대량으로 등록 가능합니다.

고객사가 관리중인 파일을 이용하여 대량으로 등록할 경우 CSV파일 형식만 처리 가능합니다. 파일의 양식은 샘플파일을 다운로드하여 참고할 수 있습니다.

API를 활용한 등록¶

COMPANY_ADMIN, DIRECTOR 계정은 관리하고자 하는 차량을 등록할 수 있습니다. DIRECTOR 계정으로 차량을 생성할 경우 담당 관리자로 해당 DIRECTOR가 설정됩니다. 협력사 계정으로 차량을 등록할 경우 운영사가 차량을 사용할 수 있도록 운영사를 CTOV에 추가합니다.

요청 파라미터를 입력할 때 mileage는 0을 초과해야 합니다. 파라미터를 누락하거나 0을 입력하면 에러 코드31(파라미터 누락 - Paramsameter ‘mileage’ can’t be empty!) 오류가 발생합니다.

차량 등록 API¶

POST

/api/tre/v1/vehicle

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Body

Key	Type	Enum	Description
vehicleNo	string		차량 번호
vendor	string		제조사
modelCode	string		모델 코드
modelName	string		모델 이름
modelYear	number		제조년도
missionType	string	AUTO MANUAL	변속기 타입
fuelType	string	DIESEL GASOLINE LPG	연료 타입
mileage	number		차량 총 주행거리
category	string	TRUCK BUS TAXI PERSONAL ETC	카테고리
usage	string		사용 용도
displacement	number		배기량
additionalInfo	string

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "vehicleNo": "00가0001",
    "vendor": "현대자동차",
    "modelCode": "G80",
    "modelName": "제네시스",
    "modelYear": 2017,
    "missionType": "AUTO",
    "fuelType": "DIESEL",
    "mileage":1,
    "category": "PERSONAL",
    "usage": "배송용",
    "displacement": 1999,
    "additionalInfo": "string"
}

Response (code: 200)

{
    "id": {
        "id": "45f8a100-bef0-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509532483338,
    "companyId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "directorId": {
        "id": "13814000-1dd2-11b2-8080-808080808080"
    },
    "currentDriverId": {
        "id": "13814000-1dd2-11b2-8080-808080808080"
    },
    "latestTripId": {
        "id": "13814000-1dd2-11b2-8080-808080808080"
    },
    "serviceType": "example",
    "vehicleNo": "00가0001",
    "modelName": "제네시스",
    "modelCode": "G80",
    "vendor": "현대자동차",
    "sensorCount": 0,
    "status": "DEACTIVATED",
    "additionalInfo": "string",
    "modelYear": 2017,
    "usage": "배송용",
    "category": "PERSONAL",
    "missionType": "AUTO",
    "fuelType": "DIESEL",
    "displacement": 1999,
    "mileage": 1,
    "delegateUserCount": 0,
    "lastTripMsgType": null
}

요청이 성공하면(code:200) Response에서 차량-센서 매핑할 때 사용하는 Vehicle ID를 얻을 수 있습니다. Vehicle ID는 Response 데이터에 있는 id 필드 안 id값입니다. 예시에 있는 45f8a100-bef0-11e7-8bdf-af923035d741이 Vehicle ID입니다.

처음 등록할 때 차량은 DEACTIVATED 상태로 설정됩니다.

센서 등록 (Sensor Registration)¶

Smart[Fleet] 포털을 통한 등록¶

운영사 및 협력사Admin 계정으로 로그인 후 센서메뉴에서 등록 가능합니다.

센서 리스트에서 등록버튼을 눌러 등록화면으로 이동합니다.

차량 등록 시 1대씩 등록하거나 파일을 이용하여 대량으로 등록 가능합니다.

4. 고객사가 관리중인 파일을 이용하여 대량으로 등록할 경우 CSV파일 형식만 처리 가능합니다. 파일의 양식은 샘플파일을 다운로드하여 참고할 수 있습니다.

API를 활용한 등록¶

센서는 COMPANY_ADMIN 권한을 가진 회사 계정으로만 등록할 수 있습니다.

센서 등록 API¶

POST

/api/tre/v1/sensor

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Body

Key	Type	Enum	Description
serialNo	string		센서 Serial No.
credentialsId	string		Access Token
vendor	string		제조사
type	string	OBD2 ADAS	센서 타입
activationRequired	boolean		RPC로 센서 활성화 필요한지 여부
missionType	string		변속기 타입
additionalInfo	string		추가 정보

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "serialNo": "A1",
    "credentialsId": "00000000000000000002",
    "vendor": "sk",
    "type": "OBD2",
    "activationRequired": true,
    "additionalInfo": "string"
}

Response (code: 200)

{
    "id": {
        "id": "05a55bc0-bf63-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509581767542,
    "vehicleId": {
        "id": "13814000-1dd2-11b2-8080-808080808080"
    },
    "companyId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "directorId": {
        "id": "13814000-1dd2-11b2-8080-808080808080"
    },
    "status": "DEACTIVATED",
    "vendor": "sk",
    "type": "OBD2",
    "additionalInfo": "string",
    "lastTripMsgType": null,
    "activationRequired": true,
    "vehicleNo": null,
    "serialNo": "A1",
    "credentialsId": "00000000000000000002"
}

요청이 성공하면(code:200) Response에서 차량과 센서를 매핑할 때 사용하는 Sensor ID를 얻을 수 있습니다. Sensor ID는 Response 데이터에 있는 id 필드 내의 id 값입니다. 예시에 있는 45f8a100-bef0-11e7-8bdf-af923035d741이 Sensor ID입니다.
처음 등록할 때 센서는 DEACTIVATED 상태로 설정됩니다. 해당 센서의 activationRequired 필드가 false이면 DEACTIVATED상태일 때도 차량과 매핑이 가능합니다. 매핑하면 ACTIVATED 상태가 됩니다.

디렉터 등록 (Director Registration)¶

Smart[Fleet] 포털을 통한 등록¶

운영사 및 협력사 Admin로그인 후 각 회사의 디렉터를 등록할 수 있습니다.

디렉터 리스트에서 등록 버튼을 눌러 등록 페이지로 이동합니다.

필수 정보를 입력한 후 등록버튼을 누르면 입력한 이메일로 디렉터 등록 안내메일이 발송됩니다.

수신한 협력사 등록신청 메일에서 비밀번호를 등록하면 협력사 계정 생성이 완료됩니다. ID는 입력한 이메일주소이며 비밀번호는 메일을 통해 등록한 비밀번호 입니다.

API를 활용한 등록¶

디렉터는 COMPANY_ADMIN 권한을 가진 회사 계정으로만 등록할 수 있습니다. 특정 차량들에 대해 관리자로 지정되어 관리하거나, 타 회사의 차량을 위임받아서 모니터링 할 수 있습니다.

디렉터 정보 등록 API¶

POST

/api/tre/v1/director

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Body

Key	Type	Description
name	string	디렉터 이름
email	string	이메일
phone	string	연락처
password	string	패스워드

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "name": "디렉터C",
    "email": "directorc@example.com",
    "phone": "010-0000-0000",
    "password": "1234",
}

Response (code: 200)

{
    "id": {
        "id": "8e904530-c06c-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509695813887,
    "companyId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "name": "디렉터C",
    "phone": "010-0000-0000",
    "vehicleId": null,
    "latestTripId": {
        "id": "13814000-1dd2-11b2-8080-808080808080"
    },
    "email": "directorc@example.com",
    "authority": "DIRECTOR",
    "password": null,
    "additionalInfo": null,
    "passwordUpdatedTime": 1509695813887
}

등록할 때 입력한 email이 아이디입니다. Example Code에서 아이디는 directorc@example.com 이고, 패스워드는 1234 입니다. Authority 필드를 통해 해당 계정이 DIRECTOR 계정인지 DRIVER 계정인지 구분할 수 있습니다.

운전자 등록 (Driver Registration)¶

Smart[Fleet] 포털을 통한 등록¶

운영사 및 협력사 Admin로그인 후 각 회사의 드라이버를 등록할 수 있습니다.

드라이버 리스트에서 등록 버튼을 눌러 등록 페이지로 이동합니다.

필수 정보를 입력한 후 등록버튼을 누르면 드라이버의 등록이 완료됩니다.

API를 활용한 등록¶

운전자는 COMPANY_ADMIN 권한을 가진 회사 계정으로만 등록할 수 있습니다. 차량 운행 서비스를 이용할 수 있습니다.

운전자 등록 API¶

POST

/api/tre/v1/driver

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Body

Key	Type	Description
name	string	운전자 이름
email	string	이메일
phone	string	연락처
password	string	패스워드

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "name": "드라이버B",
    "email": "driverb@example.com",
    "phone": "010-0000-0000",
    "password": "1234"
}

Response (code: 200)

{
    "id": {
        "id": "69b5f470-c06d-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509696181554,
    "companyId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "name": "드라이버B",
    "phone": "010-0000-0000",
    "vehicleId": null,
    "latestTripId": {
        "id": "13814000-1dd2-11b2-8080-808080808080"
    },
    "email": "driverb@example.com",
    "authority": "DRIVER",
    "password": null,
    "additionalInfo": null,
    "passwordUpdatedTime": 1509696181554
}

등록할 때 입력한 email이 아이디가 됩니다. Example Code에서 아이디는 driverb@example.com 이고, 패스워드는 1234 입니다. Authority 필드를 통해 해당 계정이 DIRECTOR 계정인지 DRIVER 계정인지 구분할 수 있습니다.

위임 회사 등록 (Delegated Company Registration)¶

Smart[Fleet] 포털을 통한 등록¶

운영사 Admin로그인 후 협력사 메뉴에서 각 회사를 위임 회사로 설정할 수 있습니다.

협력사 리스트에서 주요협력사 스위치를 눌러 활성화 합니다.

주요 협력사로 선택한 회사에 차량을 위임할 수 있습니다. 해당 기능은 차량 메뉴에서 이용 가능합니다.

차량 리스트 화면에서 차량 위임버튼을 눌러 위임 화면으로 이동합니다.

차량 선택 후 추가버튼을 눌러 차량을 선택된 차량 영역으로 이동시킨 후 다음으로 이동합니다.

위임할 회사를 검색 및 선택한 후 위임 버튼을 눌러 위임을 완료합니다.

API를 활용한 등록¶

협력 관계에 있는 회사에 차량을 위임하면 그 회사는 위임 회사가 됩니다. 그 전에 위임하는 회사가 먼저 협력사를 위임 후보 회사로 등록해야 합니다. 회사 간 ServiceType이 동일해야 합니다.

위임 후보 회사 등록 API¶

POST

/api/tre/v1/company/{companyId}/relation/company

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Path

Key	Type	Description
companyId	string	자신의 회사 ID (위임하는 회사 ID)

Body

Key		Type	Description
toCompanyId	id	string	위임 후보로 등록할 회사 ID (위임받는 회사 ID)

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "toCompanyId": {
        "id": "def51a30-c06e-11e7-8bdf-af923035d741"
    }
}

Response (code: 200)

{
    "id": {
        "id": "50117bd0-c071-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509697451337,
    "fromCompanyId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "toCompanyId": {
        "id": "def51a30-c06e-11e7-8bdf-af923035d741"
    },
    "serviceType": "example",
    "fromCompanyName": "운영사A",
    "toCompanyName": "협력사C"
}

위임 후보 회사로 등록되어 있는 회사에 특정 차량을 위임할 수 있습니다. 차량을 위임받은 회사는 위임 후보가 아닌 위임 회사가 됩니다.

위임 후보 회사에 차량 위임 API¶

POST

/api/tre/v1/director/{directorId}/relation/vehicle

Header

Key	Type	Description
toCompanyId	string	차량을 위임받을 회사 ID

Path

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Body

Key		Type	Description
vehicleId	id	string	위임할 차량 ID

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "vehicleId": {
        "id": "45f8a100-bef0-11e7-8bdf-af923035d741"
    }
}

Response (code: 200)

{
    "id": {
        "id": "1a598a90-c072-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509698195891,
    "fromCompanyId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "fromCompanyName": "운영사A",
    "toCompanyId": {
        "id": "def51a30-c06e-11e7-8bdf-af923035d741"
    },
    "toCompanyName": "협력사C",
    "vehicleId": {
        "id": "45f8a100-bef0-11e7-8bdf-af923035d741"
    },
    "vehicleNo": "00가0001"
}

위임 디렉터 등록 (Delegated Director Registration)¶

Smart[Fleet] 포털을 통한 등록¶

차량을 디렉터에게 할당하는 기능으로 운영사 및 협력사 Admin계정으로 로그인 후 차량메뉴에서 위임 가능합니다.

차량 리스트 화면에서 차량 할당버튼을 눌러 할당 화면으로 이동합니다.

차량 선택 후 추가버튼을 눌러 차량을 선택된 차량 영역으로 이동시킨 후 다음으로 이동합니다.

할당할 디렉터를 검색 및 선택한 후 위임 버튼을 눌러 위임을 완료합니다.

API를 활용한 등록¶

Company_Admin, Director 권한 계정은 Director 에게 특정 차량의 권한을 위임할 수 있습니다. API를 통해 권한이 설정된 디렉터는 할당된 차량에 대해 Delegated_director 권한을 가집니다. Company_admin은 자신의 회사에 속한 차량 또는 위임 회사에 할당한 차량에 대해서만 본인이 속한 회사의 Director에게 권한을 설정 할 수 있습니다. Director는 본인이 관리하는 차량에 한해서 다른 Director 를 Delegated Director로 설정 할 수 있습니다. 단, Director 가 다른 회사 소속일 경우에는 위임 회사에 차량 위임 권한을 가진 Director일 경우에만 권한 위임이 가능합니다.

디렉터 정보 등록 API¶

POST

/api/tre/v1/director/{directorId}/relation/vehicle

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Path

Key	Type	Description
directorId	string	차량을 위임받을 디렉터 ID

Body

Key		Type	Description
vehicleId	id	string	위임할 차량 ID

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "vehicleId": {
        "id": "45f8a100-bef0-11e7-8bdf-af923035d741"
    }
}

Response (code: 200)

{
    "id": {
        "id": "74d18670-c073-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509698777167,
    "companyId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "companyName": "운영사A",
    "userId": {
        "id": "8e904530-c06c-11e7-8bdf-af923035d741"
    },
    "userName": "디렉터C",
    "vehicleId": {
        "id": "45f8a100-bef0-11e7-8bdf-af923035d741"
    },
    "vehicleNo": "00가0001",
    "userRole": "DELEGATED_DIRECTOR"
}

위임 운전자 등록 (Delegated Driver Registration)¶

Smart[Fleet] 포털을 통한 등록¶

운영사 및 협력사 어드민, 디렉터 계정으로 로그인하여 차량 메뉴에서 등록 가능합니다.

차량 정보를 눌러 상세페이지로 이동합니다.

차량 상세 정보의 드라이버 영역에 드라이버 이름을 입력하면 자동으로 검색된 리스트가 표시되며 리스트에세 드라이버를 선택 후 수정버튼을 눌러 저장합니다.

API를 활용한 등록¶

Company_admin, director 권한 계정은 Driver 에게 특정 차량을 운행 할 수 있는 권한을 위임할 수 있습니다. API를 통해 권한이 설정된 Driver 는 해당 차량에 대해 delegated_driver 권한을 가집니다. Company_admin은 자신의 회사에 속한 차량 또는 위임회사에 할당된 차량에 대해서만 본인이 속한 회사의 driver에게 권한을 설정 할 수 있습니다.

Director는 본인이 관리하는 차량이거나 본인이 Delegated_director로 등록된 차량에 한해서 본인이 속한 회사의 driver에게 권한을 설정 할 수 있습니다.

Driver에게 이용 가능한 차량 등록 API¶

POST

/api/tre/v1/driver/{driverId}/relation/vehicle

Header

option	Type	Default	Description
Content-Type	string	application/json	content type
X-authorization	string		auth token

Path

Key	Type	Description
driverId	string	차량을 위임받을 드라이버 ID

Body

Key		Type	Description
vehicleId	id	string	위임할 차량 ID

Example Code

Request

content-type:"application/json"
X-Authorization: "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJzeXNhZG1pbkB0aG…"

{
    "vehicleId": {
        "id": "45f8a100-bef0-11e7-8bdf-af923035d741"
    }
}

Response (code: 200)

{
    "id": {
        "id": "9b631230-c074-11e7-8bdf-af923035d741"
    },
    "createdTime": 1509699271373,
    "companyId": {
        "id": "c7fc12a0-beea-11e7-8bdf-af923035d741"
    },
    "companyName": "운영사A",
    "userId": {
        "id": "69b5f470-c06d-11e7-8bdf-af923035d741"
    },
    "userName": "드라이버B",
    "vehicleId": {
        "id": "45f8a100-bef0-11e7-8bdf-af923035d741"
    },
    "vehicleNo": "00가0001",
    "userRole": "DRIVER"
}

Device 연동 절차¶

이 매뉴얼은 Smart[Fleet] 플랫폼에 연결되는 단말장치를 개발하는 파트너들을 위한 것입니다. 장치가 어떻게 플랫폼과 통신하는지 설명합니다.

Smart[Fleet] 플랫폼을 사용하여 커넥티드 카 사업을 하고자 하는 파트너는 4. 구성요소(Entity) 등록 를 참고하십시오. App 개발자는 6. API 규격 과 7. SDK 를 참고하십시오.

이 매뉴얼에서는 단말이 Smart[Fleet] 플랫폼과 어떻게 연결되는지 설명합니다. 실제 단말과 Smart[Fleet]이 주고받는 메시지에 대한 상세한 내용은 8. 메시지 포맷 을 참고하십시오.

Device Connection¶

Smart[Fleet] 플랫폼은 단말과 연동을 위해 MQTTS 프로토콜을 사용합니다. MQTTS 프로토콜은 무선 및 낮은 대역폭 네트워크에서 저전력 기기에서 사용되는 것을 목표로 만들어진 메시징 프로토콜입니다. 자세한 내용은 MQTT.org 를 참고하시기 바랍니다.

단말이 MQTTS 프로토콜을 통해 Smart[Fleet] 플랫폼과 연동할 때 다음의 설정 값이 필요합니다.

구분	Value
URL	smartfleet.sktelecom.com
Port	8883
username	할당 받은 Access Token (20자리) 값
password	N/A
cleanSession	True
version	3.1.1

Username 필드에는 해당 단말의 Credentials ID 값을 입력합니다. 단말의 Credentials ID 값은 Smart[Fleet] REST API 를 통해서 얻을 수 있습니다. cleanSession 필드가 true면 이전 세션 정보가 아직 존재할 경우 클라이언트와 서버에서 이전 세션 정보를 삭제합니다. MQTT 버전은 3.1.1을 사용합니다.

Example Code

const mqtt = require('mqtt');

const client = mqtt.connect('mqtts://smartfleet.sktelecom.com:8883',{
    username : "",
    clean : true,
    rejectUnauthorized : false
});

Device Activation¶

단말과 Smart[Fleet] 플래폼이 연동되기 위해서는 단말이 Smart[Fleet]에 등록되어 있어야 합니다. 이후 단말의 종류에 따라 단말 활성화(Device Activation) 과정이 필요할 수도 있습니다.

일부 OBD 단말은 정보를 올리기 위해서는 차량과 매핑을 통해 가져올 수 있는 센서 데이터들을 설정해야 합니다. 차량의 모델, 배기량, 연료 타입 등에 따라 측정 가능한 센서 데이터의 개수와 종류가 달라질 수 있기 때문입니다. OBD가 측정 할 수 있는 센서 데이터의 종류가 100가지 있다고 가정하면 차량 A는 50가지, 차량 B는 40가지 이렇게 차량마다 측정 데이터가 다를 수 있습니다. 이를 위해 차량에 맞는 데이터만 가져오도록 설정하는 작업이 단말 활성화 절차(Device Activation)입니다.

Activation이 필요한 단말의 등록 절차, Activation이 필요하지 않는 단말의 등록 절차 를 차례대로 알아보겠습니다.

Activation이 필요한 단말의 등록 절차¶

센서 동작 전 센서의 활성화(Activation)가 요구되는 단말에 적용되는 등록 절차를 기술합니다.

Prestep¶

사전에 각 단말은 SKT에서 제공한 Access Token (Sensor API의 credentialsId 필드)을 보유하고 있어야 하며, Application (고객사)에서도 동일한 Access Token을 보유하고 있어야 합니다.

Procedure¶

Application Owner가 포털이나 HTTPS API를 통하여 플랫폼에 단말의 정보를 등록합니다. 센서 등록 설명은 4.4. 센서 등록 (Sensor Registration) 절차를 참고합니다.

플랫폼은 1번 과정에서 요청받은 정보를 기반으로 단말을 등록합니다. 상기 등록 과정에서 오류가 발생한 경우에는 수신 받은 인터페이스에 따라 회신합니다.

단말을 플랫폼에 연결을 시도합니다. 세부 절차는 5.1. Device Connection 절차를 참고합니다.

단말이 연결되면 세션이 생성됩니다. 세션이 생성된 후 RPC 요청을 수신하기 위해 토픽을 구독합니다. MQTTS에서 토픽을 구독하면 필터에 일치하는 토픽에 대한 발행물이 클라이언트로 송신됩니다. 여기서 필터에 일치하는 발행물은 해당 단말에 대한 RPC 요청이 됩니다.
RPC 요청을 수신하는 토픽은 아래와 같습니다.

Topic

v1/sensors/me/rpc/request/+

Example Code

client.subscribe("v1/sensors/me/rpc/request/+");

차량과 등록된 센서 간 매핑을 요청합니다. 매핑 API는 아래와 같습니다.

POST

/api/tre/v1/sensor/{sensorId}/vehicle/{vehicleId}

플랫폼에서 요청 받은 단말이 Activation이 필요한지 여부를 판단합니다. 단말의 Activation 필요 여부는 플랫폼에 단말을 등록할 때 입력한 activationRequired 필드 값에 따라 구분합니다. activationRequired 값이 true이면 Activation이 필요하다고 간주합니다.

상기 6번 과정에서 단말이 Activation이 필요하다고 명시된 경우 플랫폼은 해당 단말에 Activation 정보를 내려주기 위한 RPC를 제공합니다.
메시지 포맷은 8.4.2. Device Activation의 Request 항목을 참고합니다.

단말이 7번 단계의 Activation 요청을 수신합니다.

단말은 이에 따라 Activation 수행 예정이라는 메세지를 플랫폼에 전달합니다.
메시지 포맷은 8.4.2. Device Activation의 Response 항목을 참고합니다.
해당 메세지를 발송하는 토픽은 아래와 같습니다.

Topic	v1/sensors/me/rpc/response/{Request-ID}
메시지 포맷	Response

플랫폼이 고객사(포털 또는 HTTP Response)에게 9번 과정의 단말 RPC 메시지 수신 상태를 전달합니다. 이는 매핑과 Activation은 추후에 진행되는 것을 명시합니다.

단말이 Activation을 수행한 후에 Activation 결과를 단말이 플랫폼에 전달합니다. Activation 작업은 일반적으로 일정 시간이 걸릴 수 있습니다.
Activation 결과를 발송하는 토픽은 아래와 같습니다.

Topic	v1/sensors/me/rpc/result/{Request-ID}
메시지 포맷	Result

플랫폼은 수신한 Activation 결과를 저장하고 정상적으로 Activation이 된 경우 단말과 차량을 매핑합니다.

플랫폼은 12번의 결과를 고객사에 전달합니다.

Activation이 필요하지 않는 단말의 등록 절차¶

단말 동작 전 단말의 활성화(Activation)가 요구되지 않는 단말에 적용되는 등록 절차를 기술합니다.

Prestep¶

사전에 각 단말은 SKT에서 제공한 Access Token (Sensor API의 credentialsId 필드)을 보유하고 있어야 하며, Application (고객사)에서도 동일한 Access Token을 보유하고 있어야 합니다.

Procedure¶

Application Owner가 포털이나 HTTPS API를 통하여 플랫폼에 단말의 정보를 등록합니다. 센서 등록 설명은 4.4. 센서 등록 (Sensor Registration) 절차을 참고합니다.

플랫폼은 1번 과정에서 요청받은 정보를 기반으로 단말을 등록합니다. 상기 등록 과정에서 오류가 발생한 경우에는 수신 받은 인터페이스에 따라 회신합니다.

단말과 플랫폼간 연결을 시도합니다. 세부 절차는 5.1. Device Connection 내용을 참고합니다.

단말이 연결되면 세션이 생성됩니다. 세션이 생성된 후 RPC 요청을 수신하기 위해 토픽을 구독합니다. MQTTS에서 토픽을 구독하면 필터에 일치하는 토픽에 대한 발행물이 클라이언트로 송신됩니다. 여기서 필터에 일치하는 발행물은 해당 단말에 대한 RPC 요청이 됩니다.
RPC 요청을 수신하는 토픽은 아래와 같습니다.

Topic

v1/sensors/me/rpc/request/+

Example Code

client.subscribe("v1/sensors/me/rpc/request/+");

차량과 등록된 센서 간 매핑을 요청합니다. 매핑 API는 아래와 같습니다.

POST

/api/tre/v1/sensor/{sensorId}/vehicle/{vehicleId}

플랫폼에서 요청 받은 단말이 Activation이 필요한지 여부를 판단합니다. 단말의 Activation 필요 여부는 플랫폼에 단말을 등록할 때 입력한 activationRequired 필드 값에 따라 구분합니다. activationRequired 값이 false이면 Activation이 필요없다고 간주합니다.

Activation이 필요없다고 판단되면 5번 과정의 매핑 요청에 따라 센서 엔티티에 센서가 연결된 차량의 식별자를 기입하여 논리적인 링크를 구성합니다.

플랫폼이 고객사(포털 또는 HTTPS Response)에게 센서와 차량 매핑 결과를 전달합니다.

Device RPC¶

RPC는 Remote Procedure Call의 약자로 원격에 있는 함수를 호출해주는 기능을 말합니다. Device RPC는 어플리케이션에서 원격으로 센서의 기능을 호출함으로써 제어합니다. 어플리케이션에서 요청된 단말 제어 절차는 아래와 같습니다.

Pre-Step¶

5.1. Device Connection 절차를 거칩니다. 단말이 정상적으로 연결되면 세션이 생성됩니다. 세션이 생성된 후 RPC 요청을 수신하기 위해 토픽을 구독합니다. MQTTS에서 토픽을 구독하면 필터에 일치하는 토픽에 대한 발행물이 클라이언트로 송신됩니다. 여기서 필터에 일치하는 발행물은 해당 단말에 대한 RPC 요청이 됩니다.

RPC 요청을 수신하는 토픽은 아래와 같습니다.

Topic

v1/sensors/me/rpc/request/+

Example Code

client.subscribe("v1/sensors/me/rpc/request/+");

Device RPC 절차 이전에 5.3. Device Activation 절차를 거칩니다. 서비스 등록 단계에서 RPC 결과 및 단말 Attribute 변경 정보를 수신하기 위한 HTTP Server 주소를 기입 받습니다.

Procedure¶

고객사의 Application에서 단말 제어 요청이 발생합니다.

고객사의 Application이 HTTPS POST 메시지를 통해서 RPC 요청을 수행합니다. 요청 메시지 포맷은 6.2. RPC 메시지 포맷 을 참고합니다.
RPC 요청 API는 아래와 같습니다.

POST

/api/plugins/rpc/twoway/{sensorId}

플랫폼은 2번과정에서 수신한 RPC 요청 메세지를 단말에 포워딩 합니다. 이 때, 플랫폼은 RPC에 대한 요청 식별자 Request-ID를 Topic의 하나로 제공합니다.

Topic

v1/sensors/me/rpc/request/{Request-ID}

단말은 RPC 요청을 수신했다는 Ack를 플랫폼에 Return합니다. 단 해당 수신에 대한 Ack 메시지가 20초 내로 전송되지 않으면 Timeout 된 후 에러로 처리됩니다.
RPC Ack를 발송하는 토픽은 아래와 같습니다.

Topic	v1/sensors/me/rpc/response/{Request-ID}
메시지 포맷	Response 참조

플랫폼은 RPC 요청 수신 결과 메세지를 포워딩하여 Application에 상기 4번의 Response 형태로 응답합니다.

단말은 RPC 결과를 플랫폼에 전달합니다. RPC 결과를 발송하는 토픽은 아래와 같습니다.

Topic	v1/sensors/me/rpc/result/{Request-ID}
메시지 포맷	Result 참조

플랫폼은 상기 6번 과정의 Attribute가 Update 된 경우에 해당 결과를 그대로 고객사의 application에 푸시 형태로 제공합니다. 이 때 주소는 Prestep에서 정의한 HTTP Server 주소를 활용합니다.

Device Procedure¶

단말 활성화 작업까지 마쳤다면 실제로 운행 데이터를 송수신할 차례입니다. 이제 단말이 데이터를 전송하는 프로시저의 명세에 대해 알아보겠습니다.

Trip Data¶

센서에서 발생한 운행 기록을 위한 정보를 업로드 하는 절차를 기술합니다.

Prestep¶

본 가이드 문서 중 5.2. Device Activation 절차를 정상적으로 수행되어야 합니다.

Procedure¶

단말은 차량의 운행이 시작되는 순간부터 등록 시점에 명세한 주기에 따라 Microtrip 데이터를 플랫폼에 전달합니다.
플랫폼에 Microtrip 전달하는 토픽은 아래와 같습니다. QoS 값은 1로 설정합니다.

Topic	v1/sensors/me/tre
메시지 포맷	8.2. 센서 타입별 주기 메시지 포맷 의 Microtrip 참고

단말은 차량 운행이 종료된 후 운행 종료를 알리는 Trip 데이터를 플랫폼에 전달합니다.
플랫폼에 Trip 전달하는 토픽은 아래와 같습니다. QoS 값은 1로 설정합니다.

Topic	v1/sensors/me/tre
메시지 포맷	8.2. 센서 타입별 주기 메시지 포맷 의 Trip 참고

Event Data¶

센서에서 발생한 운행 이벤트 정보를 업로드 하는 절차를 기술합니다.

Prestep¶

본 가이드 문서 중 5.2. Device Activation 절차를 정상적으로 수행합니다.

Procedure¶

차량에서 플랫폼에 전달할 이벤트가 발생합니다.

1번 과정에서 발생한 이벤트를 아래 규격에 맞추어 플랫폼에 전달합니다. 이벤트는 Time Series와 Attributes 두 종류로 나눠지며 서로 다른 토픽을 사용합니다.
플랫폼에 이벤트 전달하는 토픽은 아래와 같습니다. QoS 값은 1로 설정합니다.

Topic	Time Series 이벤트인 경우	v1/sensors/me/telemetry
Topic	Attributes 이벤트인 경우	v1/sensors/me/attributes

전달 가능한 이벤트는 아래와 같습니다. 메세지 포맷은 8.2.1.1 Payload Types 를 참조합니다.

Diagnostic Information (Time Series)
Collision warning (Driving) (Time Series)
Collision warning (Paramsking) (Time Series)
Battery Warning (Attributes)
Unplugged Warning (Attributes)
Turn-off Warning (Attributes)

API 규격¶

REST API¶

Smart[Fleet] 플랫폼의 다음과 같은 REST API를 제공합니다. 상세한 내용은 Smart[Fleet] REST API Web Document 내용을 참고하시기 바랍니다.

구분	APIs
Auth	로그인 토큰 갱신 비밀번호 변경 임시비밀번호 변경 사용자 이메일 검색
Company	회사 정보 등록 회사 정보 조회 회사 정보 수정 회사 삭제 내 회사 정보 조회 특정 Service Type에 속하는 회사 리스트 조회 전체 회사 리스트 조회 특정 Service Type에 속하는 협력사의 수 조회 회사 관리자 등록 회사 관리자 수정 회사 관리자 삭제 회사 관리자 리스트 조회 소유한 차량 리스트 조회 위임받은 차량 리스트 조회 위임한 차량 리스트 조회
Director	Director 등록 Director 정보 조회 Director 삭제 특정 회사에 속하는 Director 리스트 조회 특정 회사에 속하는 Director 수 조회 관리하는 차량 리스트 조회 운행한 Trip 리스트 조회 최신 Trip 조회
Driver	Driver 등록 Driver 정보 조회 Driver 정보 수정 Driver 삭제 Driver 리스트 조회 Driver 수 조회 운행한 Trip 리스트 조회 최신 Trip 조회
Vehicle	차량 등록 차량 번호로 차량 조회 차량 정보 조회 차량 정보 수정 차량 삭제 ServiceType에 속하는 전체 차량 수 조회 소유 차량 수 조회 소유 차량중에 센서가 부착되지 않은 차량 수 조회 현재 운행중인 차량 수 조회 Director 설정 Director 해제 운행한 Trip 리스트 조회 최신 Trip 조회 최신 MicroTrip 조회 차량 활성화/비활성화 Driver 설정 Driver 해제 차량을 위임한 회사 리스트 조회
Sensor	센서 등록 Serial No로 센서 조회 센서 정보 조회 센서 정보 수정 센서 삭제 센서 최신 값 조회 차량에 센서 장착 차량에서 센서 분리 센서 리스트 조회 차량에 장착되지 않은 센서 리스트 조회 ServiceType의 전체 센서 수 소유한 전체 센서 수 소유한 센서 중 차량에 장착되지 않은 센서 수 RPC 전송 RPC 결과 조회 RPC 결과 리스트 조회 최신 RPC 결과 조회
Trip	MicroTrip 리스트 조회
Relation	위임후보 회사 등록 위임후보 회사 제외 위임후보 회사 리스트 조회 위임후보 회사에 차량 위임 위임한 회사에서 차량 위임 해제 Director에게 이용 가능한 차량 등록 위임한 Director 정보 조회 위임한 Director에서 차량 위임 해제 Director에게 위임된 차량 리스트 조회 Driver에게 이용가능한 차량 등록 위임한 Driver 정보 조회 위임한 Driver 차량 위임 해제 Driver에게 위임된 차량 리스트 조회

Entity Model¶

REST API에서는 다음과 같은 Entity들이 정의되어 있으며, 세부 데이터 모델 내용은 Smart[Fleet] REST API Web Document 내용을 참고하시기 바랍니다.

JWT
Company
User
Vehicle
Sensor
Trip
MicroTrip
CompanyToCompany
CompanyToVehicle
UserToVehicle
RPCRequest
RPCResponse
RPCResult
TextPageLink
TimePageLink

이 매뉴얼은 단말이 MQTTS 프로토콜로 Smart[Fleet] 플랫폼과 연동하기 위한 메시지 포맷입니다. Entity 등록을 위한 HTTP Rest API 사용은 4. 구성요소(Entity) 등록 문서를, App 개발자를 위한 Smart[Fleet] API 는 6. API 규격 문서를 참고하십시오.

메시지 기본 구조¶

Smart[Fleet] 플랫폼의 기본 메시지 구조는 Header 와 Payload 형태로 구조화 되어 있습니다. 각 메시지는 해당 메시지의 타입인 ty 로 구분하고 ty 에 따라 pld child의 내용이 상이합니다.

Example Code :

{
    // Header
    "ts" : 1505434907995,
    "ty" : 2,

    // Payload
    "pld" : {
        "tid" : 1,
        "fc" : 12,
        "lon" : 127.114513,
        "lat" : 37.380241,
        "rpm" : 323,
        "em" : 28,
        "el" : 25,
        "xyz" : "23123,49923,123",
        "vv" : "11.4"
    }
}

센서 타입별 주기 메시지 포맷¶

GPS¶

GPS 단말에서 발생한 위치 데이터를 플랫폼에 전달하기 위해 필요한 메시지를 정의합니다.

Message Header¶

Key

Type

M/O

Description

ty

Int

M

전달하고자 하는 페이로드 타입

Trip_GPS
Microtrip_GPS

ts

Int

O

정보 수집 시간

pld

M

아래 각 페이로드 메시지를 참고

Note

표에 M/O는 Mandatory/Optional의 약자로, Mandatory는 필수로 포함해야하는 데이터를 Optional은 필요에 따라 기입이 여부를 개발사에 판단합니다.

Payload Types¶

GPS Trip Message¶

Trip Message는 차량이 운행이 종료된 후에 전달하는 메시지입니다.

Key	Type	M/O	Description	Note
tid	Int	M	Trip 고유 번호
stt	Int	M	Trip의 시작 날짜 및 시간	UTC
edt	Int	M	Trip의 종료 날짜 및 시간	UTC
dis	Int	O	Trip의 주행거리	Meter
stlat	Int	O	운행 시작 좌표의 위도
stlon	Int	O	운행 시작 좌표의 경도
edlat	Int	O	운행 종료 좌표의 위도
edlon	Int	O	운행 종료 좌표의 경도
hsts	Int	O	Trip의 최고 속도
mesp	Int	O	Trip의 평균 속도
fwv	String	O	펌웨어 버전
dtvt	Int	O	주행시간

Example Code :

{
    "ty" : 1,
    "ts" : 1505434907995,
    "pld" : {
          "tid" : 10,
          "stt" : 1505433907995,
          "edt" : 1505434907995,
          "dis" : 101,
          "stlon" : 127.114513,
          "stlat" : 37.380241,
          "edlon" : 126.114513,
          "edlat" : 36.380241,
          "hsts" : 121,
          "mesp" : 63,
          "fwv" : "1.0.1",
          "dtvt" : 88
    }
}

GPS Microtrip¶

Microtrip 메세지는 차량이 운행을 시작한 후 설정된 주기에 따라 전송하는 차량 운행에 대한 위치 데이터입니다. 주기는 각 어플리케이션 마다 상이하므로, 아래의 값은 플랫폼에 전송하는 해당 시점에 데이터를 추출하여 기입합니다.

Key	Type	M/O	Description
tid	Int	M	Trip 고유 번호
lat	Int	M	위도 (WGS84)
lon	Int	M	경도 (WGS84)
alt	Int	M	고도 (WGS84)
clt	Int	M	단말기 기준 수집 시간
sp	Int	O	Ground Speed (based on NMEA Protocol / km/h)
dop	Int	O	Dilution of Precision 값 (based on NMEA protcol)
nos	Int	O	위성 갯수 정보 (based on NMEA protocol)
tdis	Int	O	Microtrip 동안 이동한 거리

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 2,
    "pld" : {
          "tid" : 1,
          "lon" : 127.114513,
          "lat" : 37.380241,
          "alt" : 280.2,
          "clt" : 1505434907995,
          "sp" : 10.2,
          "dop" : 15.2,
          "nos" : 5
    }
}

Aggregated Microtrip¶

Microtrip 데이터는 여러개의 데이터를 모아서 한번에 보낼 수 있습니다. 각 수집한 Microtrip 데이터는 JSON Array 데이터를 기반으로 다음과 같이 패킷을 합쳐 보낼 수 있습니다.

{
    "ty":2,
    "ts":1508215121898,
    "pld":
    [
        {
            "tid":301,
            "lon":127.062512,
            "lat":37.510296,
            "alt":102,
            "sp":90,
            "dop":13,
            "nos":5,
            "clt":1508215121888
        },
        {
            "tid":301,
            "lon":127.062512,
            "lat":37.510296,
            "alt":113,
            "sp":74,
            "dop":11,
            "nos":4,
            "clt":1508215121893
        },
        {
            "tid":301,
            "lon":127.062512,
            "lat":37.510296,
            "alt":115,
            "sp":71,
            "dop":14,
            "nos":5,
            "clt":1508215121898
        }
    ]
}

Note

페이로드가 Microtrip 여러개를 Aggregation 하여 전송할 때는 시간의 순서에 맞추어 전송하여야 합니다. 플랫폼에서 시간에 따라 Re-ordering을 수행하지 않습니다.

OBD¶

OBD 단말에서 발생한 데이터를 플랫폼에 전달하기 위해 필요한 메시지를 정의합니다.

Message Header¶

Key

Type

M/O

Description

ty

Int

M

전달하고자 하는 페이로드 타입

Trip_OBD
Microtrip_OBD

ts

Int

O

정보 수집 시간

pld

M

아래 각 페이로드 메시지를 참고

Payload Type¶

OBD Trip¶

Trip Message는 차량이 운행이 종료된 후에 전달하는 메시지입니다.

Key	Type	M/O	Description	Note
tid	Int	M	Trip 고유 번호
stt	Int	M	Trip의 시작 날짜 및 시간	UTC
edt	Int	M	Trip의 종료 날짜 및 시간	UTC
dis	Int	M	Trip의 주행거리	Meter
tdis	Int	M	차량의 총 주행거리	Meter
fc	Int	M	연료소모량
stlat	Int	M	운행 시작 좌표의 위도
stlon	Int	M	운행 시작 좌표의 경도
edlat	Int	M	운행 종료 좌표의 위도
edlon	Int	M	운행 종료 좌표의 경도
ctp	Int	M	부동액(냉각수) 평균온도
coe	Int	M	Trip의 탄소 배출량
fct	Int	M	연료차단 상태의 운행시간
hsts	Int	M	Trip의 최고 속도
mesp	Int	M	Trip의 평균 속도
idt	Int	M	Trip의 공회전 시간
btv	Int	M	배터리 전압(시동OFF후 전압)
gnv	Int	M	발전기 전압(주행중 최고 전압)
wut	Int	M	Trip의 웜업시간(주행전 시동 시간)
usm	Int	O	BT가 연결된 휴대폰 번호
est	Int	O	80~100km 운행 시간
fwv	Int	O	펌웨어 버전
dtvt	Int	O	주행시간

Example Code :

{
    "ty" : 1,
    "ts" : 1505434907995,
    "pld" : {
        "tid" : 10,
        "stt" : 1505433907995,
        "edt" : 1505434907995,
        "dis" : 101,
        "tdis" : 16813,
        "fc" : 83,
        "stlon" : 127.114513,
        "stlat" : 37.380241,
        "edlon" : 126.114513,
        "edlat" : 36.380241,
        "ctp" : 48,
        "coe" : 392,
        "fct" : 123,
        "hsts" : 121,
        "mesp" : 63,
        "idt" : 3,
        "btv" : 14.5,
        "gnv" : 12.3,
        "wut" : 181,
        "dtvt" :2301
    }
}

OBD Microtrip¶

Microtrip 메세지는 차량이 운행을 시작한 후 설정된 주기에 따라 전송하는 차량 운행 상세 데이터입니다. 주기는 각 어플리케이션 마다 상이하므로, 아래의 값은 플랫폼에 전송하는 해당 시점에 데이터를 추출하여 기입합니다.

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 2,
    "pld" : {
        "tid" : 1,
        "fc" : 12,
        "lon" : 127.114513,
        "lat" : 37.380241,
        "rpm" : 323,
        "em" : 28,
        "el" : 25,
        "xyz" : "23123,49923,123",
        "vv" : "11.4"
    }
}

ADAS¶

ADAS 단말에서 발생한 데이터를 플랫폼에 전달하기 위해 필요한 메시지를 정의합니다.

Message Header¶

Key

Type

M/O

Description

ty

Int

M

전달하고자 하는 페이로드 타입

Trip_ADAS
Microtrip_ADAS

ts

Int

O

정보 수집 시간

pld

M

아래 각 페이로드 메시지를 참고

Payload Type¶

ADAS Trip¶

ADAS Trip 메세지는 ADAS 단말이 주행을 완료한 경우에 사용하는 메시지 포맷입니다.

Key	Type	M/O	Description
tid	Int	M	Trip 고유 번호
lat	Int	M	운행 종료 시 위도 (WGS84)
lon	Int	M	운행 종료 시 경도 (WGS84)
dop	Int	O	Dilution of Precision 값 (based on NMEA protcol)
nos	Int	O	위성 갯수 정보 (based on NMEA protocol)

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 5,
    "pld" : {
        "tid" : 11123,
        "lon" : 127.114513,
        "lat" : 37.380241,
    }
}

ADAS Microtrip¶

ADAS Microtrip 메세지는 ADAS 단말에서 인지한 ADAS 및 GPS 위치 정보를 주기적으로 올릴때 사용하는 메시지 포맷입니다. 일반적으로는 ADAS와 GPS가 함께 있는 경우에 활용하며, 메시지는 ADAS 부착 차량의 운행 시작부터 운행 종료까지 주기적으로 전송합니다.

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 6,
    "pld" : {
        "tid" : 11123,
        "lon" : 127.114513,
        "lat" : 37.380241,
        "sp" : 113,
        "dir" : 31,
        "ldw" : 32,
        "rld" : 20,
        "lld" : 50,
        "fcw" : 30,
        "hdw" : 50,
        "brk" : 0,
        "chcmr" : 0,
        "chdir" : 0,
        "chbrk" : 0
    }
}

BlackBox¶

BlackBox 단말에서 발생한 데이터를 플랫폼에 전달하기 위해 필요한 메시지를 정의합니다.

Message Header¶

Key

Type

M/O

Description

ty

Int

M

전달하고자 하는 페이로드 타입

Trip_BlackBox
Microtrip_BlackBox

ts

Int

O

정보 수집 시간

pld

M

아래 각 페이로드 메시지를 참고

Payload Type¶

BlackBox Trip¶

BlackBox Trip 메세지는 BlackBox 단말이 주행 또는 주차 상태를 완료한 경우에 사용하는 메시지 포맷입니다. 단 BlackBox의 Trip은 주행과 주차로 설정합니다.

Key	Type	M/O	Description
tid	Int	M	Trip 고유 번호
lat	Int	M	운행 종료 시 위도 (WGS84)
lon	Int	M	운행 종료 시 경도 (WGS84)
try	Int	M	Trip 타입 Driving Parking
vlt	Int	M	자동차 배터리 전압 (운행 종료 시)

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 7,
    "pld" : {
        "tid" : 11123,
        "lon" : 127.114513,
        "lat" : 37.380241,
        "try" : 1,
        "vlt" : 12.1
    }
}

BlackBox Microtrip¶

BlackBox Microtrip 메세지는 Blackbox 단말에서 인지한 정보를 주기적으로 플랫폼에서 사용하는 메시지 포맷입니다. 일반적으로는 ADAS와 GPS가 함께 있는 경우에 활용하며, 메시지는 ADAS 부착 차량의 운행 시작부터 운행 종료까지 주기적으로 전송합니다.

Key	Type	M/O	Description
tid	Int	M	Trip 고유 번호
try	Int	M	Trip 타입 Driving Parking
lat	Int	O	위도 (WGS84) `Mandatory when Driving`
lon	Int	O	경도 (WGS84) `Mandatory when Driving`
sp	Int	O	Ground Speed (based on NMEA Protocol, km/h) `Mandatory when Driving`
vlt	Int	O	자동차 배터리 전압 `Mandatory when Parking`
tem	Int	O	자동차 내부 온도 `Mandatory when Parking`
tim	Int	O	주차 시간 (or 주차 남은 시간) `Mandatory when Parking`

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 6,
    "pld" : {
        "tid" : 11123,
        "try" : 1
        "lon" : 127.114513,
        "lat" : 37.380241,
        "sp" : 113,
    }
}

이벤트 데이터 포맷¶

단말에서 비주기적으로 발생한 이벤트를 플랫폼에 전송하기 위한 메시지 포맷입니다. 이벤트 기반 데이터 전송을 위한 프로시저는 5.4.2 Event Data 를 참고하십시오.

Message Header¶

Key

Type

M/O

Description

ty

Int

M

전달하고자 하는 이벤트 타입

Diagnostic Information

Collision warning (Driving)

Collision warning (Parking)

Battery Warning

Unplugged Warning

Turn-off Warning

ADAS Event

BlackBox Booting

BlackBox Mode Change

BlackBox Setting Report Message

BlackBox Capture Image Message

ts

Int

O

정보 수집 시간

pld

M

아래 각 페이로드 메시지를 참고

Payload Type¶

Diagnostic Information¶

OBD에서 인지한 차량 진단 코드(DTC)를 전송하는 메시지를 정의합니다.

Key	Type	M/O	Description
tid	Int	O	Trip 고유 번호(Not required)
dtcc	String	M	차량고장코드 (Delimeter Comma)
dtck	Int	M	0=confirm 1=pending 2=permanent
dtcs	Int	M	DTC Code의 개수

Note

OBD가 플랫폼에 DTC 코드를 전송하는 방식은 2가지입니다.

차량 주행이 시작한 후에 감지된 Diagnostic Information을 전송하는 방법
플랫폼을 통해서 OBD에 DTC 코드 보고를 요청하는 RPC 방법

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 20,
    "pld" : {
        "tid": 1,
        "dtcc": "AAA",
        "dtck": 0,
        "dtcs": 2
    }
}

Collision warning (Driving)¶

운행 중 OBD가 감지한 차량 접촉 사고에 대한 위치 정보를 전달하는 메세지를 정의합니다.

Key	Type	M/O	Description
tid	Int	O	Trip 고유 번호
dclat	Int	M	위도 (WGS84)
dclon	Int	M	경도 (WGS84)

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 21,
    "pld" : {
        "tid": 1,
        "dclat" : 37.380241,
        "dclon" : 127.114513
    }
}

Collision warning (Parking)¶

주차 중 OBD가 감지한 차량 접촉 사고에 대한 위치 정보를 전달하는 메세지를 정의합니다.

Key	Type	M/O	Description
tid	Int	O	Trip 고유 번호
plat	Int	M	위도 (WGS84)
plon	Int	M	경도 (WGS84)

Example Code :

{
  "ts" : 1505434907995,
  "ty" : 22,
  "pld" : {
      "plat" : 37.380241,
      "plon" : 127.114513
  }
}

Battery Warning¶

차량 배터리 소모에 대한 위험 알림 메시지를 정의합니다.

Key	Type	M/O	Description
tid	Int	O	Trip 고유 번호
wbv	Int	M	배터리 전압

Example Code :

{
  "ts" : 1505434907995,
  "ty" : 23,
  "pld" : {
      "wbv" : 13
  }
}

Unplugged Warning¶

OBD가 차량으로부터 탈착되는 이벤트에 대한 알림 메시지를 정의합니다.

Key	Type	M/O	Description
tid	Int	O	Trip 고유 번호
unpt	Int	M	탈착 시간
pt	Int	M	부착 시간

Example Code :

{
  "ts" : 1505434907995,
  "ty" : 24,
  "pld" : {
      "unpt": 1505433907995,
      "pt": 1505434907995
  }
}

Turn-off Warning¶

OBD가 종료된 경우, 종료 이전에 종료에 대한 이유를 플랫폼에 전달하기 위한 알림 매시지를 정의합니다.

Key	Type	M/O	Description
tid	Int	O	Trip 고유 번호
rs	String	M	단말 종료 원인

Example Code :

{
  "ts" : 1505434907995,
  "ty" : 25,
  "pld" : {
      "rs": "unexpected reason"
  }
}

ADAS Event¶

ADAS에서 인지한 이벤트 정보를 전송하는 메시지 포맷입니다.

Example Code :

{
    "ts" : 1505434907995,
    "ty" : 26,
    "pld" : {
          "tid" : 11123,
          "lon" : 127.114513,
          "lat" : 37.380241,
          "sp" : 113,
          "dir" : 31,
          "ldw" : 32,
          "fcw" : 30
    }
}

RPC 메시지 포맷¶

OBD 단말을 제어하기 위한 RPC Message Type을 명세합니다. 기술되지 않는 제어는 단말과 어플리케이션 상호 간에만 규약 되어 있다면, Vendor Specific Message를 사용합니다.

Vendor Specific Message¶

각 단말 업체에서 별도로 관리하는 제어 요청 메시지이며, 다른 제어 메시지도 본 포맷을 확장하여 명시됩니다.

Request¶

Key	Type	M/O	Description
method	String	M	원격 제어하고자 하는 기능에 대해서 명세
params	String	M	기능에 대한 파라미터를 명세

Response¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가

Result¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가
addInfo	String	O	결과 값에 따른 추가 정보 명세

Device Activation¶

차량용 센서를 차량에 부착한 후 활성화하기 위해 필요한 RPC 메시지를 명세합니다.

Request¶

Example Code :

{
    "method" : "activationReq",
    "params" : {
        "vid" : "25나0660",
        "upp" : 1,
        "elt" : 1999,
        "fut" : 1,
        "mty" : "Automatic"
    }
}

Response¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가

Example Code :

{
    "result" : 2000
}

Result¶

Example Code :

{
    "result" : 2000,
    "addInfo" : {
        "vid" : "25나0660"
    }
}

Firmware Update¶

차량용 OBD의 펌웨어 업데이트를 위한 RPC 메시지를 명세합니다.

Request¶

Example Code :

{
    "method" : "fwupdate",
    "params" : {
        "pkv" : "1.0.1",
        "url" : "ftp://smartfleet.sktelecom.com:10011"
    }
}

Response¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가

Example Code :

{
    "result" : 2000
}

OBD Reset¶

차량용 OBD의 재시작을 위한 RPC 메시지

Request¶

Key	Type	M/O	Description
method	String	M	reset 로 명세
params	String	M	N/A

Example Code :

{
    "method" : "reset",
    "params" : ""
}

Response¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가

Example Code :

{
    "result" : 2000
}

Result¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가
addInfo	String	O	결과 값에 따른 추가 정보 명세

Example Code :

{
    "result" : 2000
}

Device Serial Number Check¶

차량용 OBD의 시리얼 번호 확인용 RPC 메시지

Request¶

Key	Type	M/O	Description
method	String	M	serial 로 명세
params	String	M	N/A

Example Code :

{
    "method" : "serial",
    "params" : ""
}

Response¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가

Example Code :

{
    "result" : 2000
}

Result¶

Example Code :

{
    "result" : 2000,
    "addInfo" : {
        "sn" : "70d71b00-71c9-11e7-b3e0-e5673983c7b9"
    }
}

Clear Device Data¶

차량용 OBD 데이터 삭제

Request¶

Key	Type	M/O	Description
method	String	M	cleardata 로 명세
params	String	M	N/A

Example Code :

{
    "method" : "cleardata",
    "params" : ""
}

Response¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가

Example Code :

{
    "result" : 2000
}

Result¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가
addInfo	String	O	N/A

Example Code :

{
    "result" : 2000
}

Firmware Update (Chunk-based)¶

Chunk 기반으로 차량용 OBD의 펌웨어 업데이트를 위한 RPC 메시지를 명세합니다.

Request¶

Example Code :

{
    "method" : "fwupchunk",
    "params" : {
        "tsz" : 4932321,
        "csz" : 10000,
        "idx" : 13,
        "pyl" : "83a27473cf0000015e82e9b55ba2747902a3706c64"
    }
}

Response¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가

Example Code :

{
    "result" : 2000
}

Result¶

Key	Type	M/O	Description
result	String	M	resultCode 에 정의된 제어 결과 추가
addInfo	String	O	N/A

Example Code :

{
    "result" : 2000
}

Common Response Code for RPC Result¶

Code Class¶

Status Class	Code	Description
Success	2XXX	RPC 결과가 정상적으로 동작하는 경우
Sensor Error	4XXX	RPC 결과를 수신한 단말이 비정상적으로 동작한 경우
Platform Error	5XXX	RPC 요청에 대해서 플랫폼이 비정상적으로 동작한 경우

Successful Response Class¶

Code	Description
2000	RPC 정상적 수행
2001	RPC 메시지 정상적으로 수신

Sensor Error Response Class¶

Code	Description
4000	디바이스가 수행할 수 없는 RPC 메시지 수신
4001	잘못된 RPC 파라미터 수신
4002	접근 불가
4003	동일한 RPC 중복 수신

테스트용 시뮬레이터¶

본 가이드 문서 중 3.4. Device 연동 절차 또는 아래 그림의 서비스 연동 기본 절차에서 볼 수 있듯이 서비스를 이용하려면 어플리케이션과 디바이스(센서) 둘다 필요합니다.

SKT에서는 개발 파트너분들 중 센서/디바이스 혹은 어플리케이션 하나만 테스트를 원할 경우를 대비하여 디바이스/센서 및 애플리케이션 대행 역할을 담당하는 테스트용 시뮬레이터를 제공합니다.

Smart[Fleet] Device Simulator¶

본 시뮬레이터는 SKT의 Smart[Fleet] 플랫폼 프로토콜을 따르는 GPS, OBD 단말의 동작을 나타내는 시뮬레이터입니다. 해당 시뮬레이터에 대한 추가 사용 설명과 프로그램 다운로드는 아래 사이트를 방문하시기 바랍니다.

Smart[Fleet] Device Simulator : https://github.com/skt-smartfleet/device-simulator-nodejs

해당 시뮬레이터는 node.js 기반으로 구현되어 있습니다. 본 시뮬레이터가 정상적으로 동작하기 위해서는 node.js가 설치되어 있어야 합니다.
동작을 위한 설정은 본 Repository의 config.js 파일에 기술되어 있습니다. 해당 설정을 수정하여 각자에 상황에 맞추어 시뮬레이션을 수행할 수 있습니다.
수정이 필요한 사항은 다음과 같습니다.

Key	Description
userName	Accesstoke 값을 기입해야 합니다. 시뮬레이션을 위한 20자리의 Token 값을 발급받기 위해서는 Repository Issue 에 이슈 등록 부탁드립니다.
updateInterval	단말이 메시지를 업로드 하는 주기를 명시합니다. (msec)
microtripcnt	단말이 주기 정보를 보내는 총 개수를 명시합니다.
deviceType	시뮬레이션을 돌리고자 하는 디바이스 타입을 명시합니다. (GPS / OBD)

Smart[Fleet] Simple Web App¶

Smart[Fleet] Simple Web App은 OBD 운행 데이터 확인 및 RPC 요청 기능을 구현한 웹 애플리케이션입니다. 추가 사용 설명과 프로그램 다운로드는 아래 사이트를 방문하시기 바랍니다.

Smart[Fleet] Web Application Simulator : https://github.com/skt-smartfleet/simpleweb

해당 애플리케이션은 node.js 기반으로 구현되어 있습니다. 본 시뮬레이터가 정상적으로 동작하기 위해서는 node.js가 설치되어 있어야 합니다.
애플리케이션을 이용하기 위해 차량, 센서 정보가 있는 Smart [Fleet] 계정과 SK플래닛 개발자센터 에서 제공하는 API 인증키가 필요합니다. 계정이 없는 경우 본 가이드 문서 4. 구성요소 등록 절차 를 참조하여 계정을 생성하시기 바랍니다. 인증키가 없는 경우 SK플래닛 개발자센터 API 이용방법 을 참조하여 인증키를 발급받으실 수 있습니다.