목차


1. SDK 기본동작 설명

어썸커넥트에서 차량의 데이터를 수신하기 위해, 어썸커넥트 앱과 연결을 진행해야합니다.
제공되는 SDK는 어썸커넥트와 연결할 수 있는 API들의 모음이며, 실제 차량과 통신 및 기능을 수행하는 역할은 어썸커넥트앱입니다.
SDK의 VehicleManager 클래스를 이용해서 에이전트앱과 상호작용을 할 수 있습니다.
VehicleManager 클래스를 사용할 클래스에 멤버로 지정하여 사용하면 편리합니다.
VehicleManager를 사용하기 위해 new 키워드로 Object 생성시 Context를 Parameter로 넘겨줘야합니다. 


import android.os.Bundle;
import com.awesomeit.vehicleplus.library.api.VehicleManager;

public class MainActivity extends AppCompatActivity {
	private VehicleManager mVehicleManager = null;  
  
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);  
		setContentView(R.layout.activity_main);  
  
		mVehicleManager = new VehicleManager(getApplicationContext());
	}
}


2. 리스너 설치하기

어썸커넥트에서 데이터를 수신하기 위해서는 데이터 수신을 하기 위한 리스너를 연결해줘야 합니다. 크게 2가지의 리스너가 있으며, 인터페이스로 구현되어 있으므로 사용할 클래스에 implements 해주면 됩니다.

  • VehicleDataListener : 자동차 데이터의 수신을 위한 리스너.
  • ConnectionListener : 연결 관련 데이터의 수신을 위한 리스너.

NOTE : 예제에서는 사용법을 안내하기 위해 MainActivity에 Interface를 연결하였습니다.


3. 어썸커넥트 연결 시나리오

VehicleManager를 생성하였다면, 본격적으로 어썸커넥트와 연결하기를 구현합니다.
어썸커넥트를 실행하기 위해서는 다음과 같은 단계가 필요합니다.

  • setOnConnectionListener(ConnectionListener) : boolean
  • connect(String, String) : void
  • onConnected(void) : void - 콜백수신
  • getSelectedVehicleDataLists()
  • onSelectedVehicleDataInfo : void - 콜백수신
  • VehicleDataRequest build()
  • subscribe(VehicleDataRequest, VehicleDataListener) : void
  • start() : boolean 호출
  • onDataReceived(VPVehicleDataTable) : void - 콜백 수신

NOTE : onDataReceived는 실제 데이터를 수신하는 콜백메서드로, JSON으로 만들어진 VPVehicleDataTable 객체를 수신합니다. VPVehicleDataTable은 String, VPVehicleData로 이루어진 HashMap을 멤버로 가지고 있습니다.


4. 어썸커넥트와 연결하기 (setOnConnectionListener, connect)

어썸커넥트와 어썸커넥트 SDK를 연결하기 위해서는 connect 메서드를 이용합니다.
connect 메서드를 사용하면 어썸커넥트에서 허용된 RemoteService에 binding 할 수 있습니다.
connect 메서드를 실행하고 어썸커넥트와 연결되면 onConnected 메서드가 콜백됩니다. 이때 onConnected 메서드의 콜백을 받기 위해서는 ConnectionListener 인터페이스를 구현(implements)하고, 리스너를 등록해주어야 합니다. 예제 코드는 다음과 같습니다. 


public class MainActivity extends AppCompatActivity implements ConnectionListener {
	private VehicleManager mVehicleManager = null;
	private String mLicenseKey = "hdlgr8iTH/EoBtqBYPEDNtnUrKj/";
	private String mDescription = "description for application";  

	@Override  
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);  
		setContentView(R.layout.activity_main);  
  
		mVehicleManager = new VehicleManager(this);  
		mVehicleManager.setOnConnectionListener(this);
	}
  
	@Override
	protected void onStart() {  
		super.onStart();
		mVehicleManager.connect(mLicenseKey, mDescription);
	}
  
	@Override  
	public void onConnected() {  
		// This callback method is called when the SDK and agent are connected.  
	}  
  
	@Override  
	public void onConnectionFailed(VPResultInfo vpResultInfo) {  

	}  
}



5. 인증시도하기 (Certifications)

connect 메서드를 이용하여 연결 시도를 수행할때, connect 메서드의 파라미터를 확인해야합니다.
connect 메서드의 파라미터로는 2가지가 필요합니다.
첫번째는 어썸잇에서 발급해야하는 암호화된 인증키이며, 두번째는 앱을 설명할 문구입니다.
어썸커넥트와 SDK는 어썸잇에서 발급한 올바른 인증키가 있어야 정상적으로 작동됩니다.
connect를 통해 연결과 인증을 정상적으로 완료하면, 설치한 onConnected로 정상적으로 연결되었다는 콜백을 수신하게 됩니다.
연결을 수행하기가 실패되면, onConnectedFailed 메서드에 실패 사유와 함께 콜백이 수신됩니다.

NOTE : 어썸잇에서 발급되는 인증키는 AES256으로 암호화된 String의 형태로 구성되어 있습니다. 간단한 등록절차를 통해 사용자 정보를 등록한 후 발급하고 있습니다. onConnectFailed 메서드의 실패 사유는 파라미터로 전달될 VPResult에 보관되어있습니다.
VPResultInfo의 getResult 메서드를 호출하여 원인을 찾아서 해결해야 합니다.


6. VehicleDataList 얻어오기

어썸커넥트에서 내가 선택한 차종에서 지원하는 데이터리스트를 얻어 올 수 있습니다.
정상적으로 연결이 확인되었다는 onConnected 콜백수신확인후 사용해야합니다.
onConnected가 호출된후 VehicleManager의 getSelectedVehicleDataList를 호출하면
onSelectedVehicleDataInfo로 내가 선택한 차종에서 지원하는 데이터리스트를 얻어올 수 있습니다.
onSelectedVehicleDataInfo는 VPSelectedVehicleDataInfo 객체를 전달하며, 이 객체의
getSelectedVehicleDataInfo 메소드를 이용하여 지원하는 데이터의 리스트를 받을 수 있습니다.


private void getVehicleDataInfo() {
	Log.d(TAG, "getVehicleDataInformation called.");
	mVehicleManager.getSelectedVehicleDataLists();
}

@Override
public void onSelectedVehicleDataInfo(VPSelectedVehicleDataInfo vpSelectedVehicleDataInfo) {
	this.mSupportedElementList = vpSelectedVehicleDataInfo.getSelectedVehicleDataInfo();
	Log.d(TAG, "list size=" + this.mSupportedElementList.size() + " list empty=" + this.mSupportedElementList.isEmpty());
}


7. VehicleDataListener 연결하기

차량의 데이터를 수신하기 위해서는 SDK의 VehicleManager의 VehicleDataListener를 구현해야합니다.
VehicleDataListener를 구현하면 onDataReceived 메서드를 Override 해줘야합니다.


import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import com.awesomeit.vehicleplus.library.api.VehicleDataListener;

public class MainActivity extends AppCompatActivity implements VehicleDataListener {
	@Override  
	protected void onCreate(Bundle savedInstanceState) {  
		super.onCreate(savedInstanceState);  
		setContentView(R.layout.activity_main);  
	} 
  
	@Override  
	public void onDataReceived(VPVehicleDataTable vpVehicleDataTable) {  
	// Here your application codes..  
	}
}

어썸커넥트에 연결 후 subscribe(VehicleDataRequest, VehicleDataListener)를 이용하여 데이터를 수신할 수 있습니다.
subscribe 메서드를 호출하고 어썸커넥트에 정상적으로 연결되어 있다면, onDataReceived(VPVehicleDataTable) 메서드가 콜백됩니다.
어썸커넥트가 데이터 통신 성공을 하면 HashMap 형태의 Paramter에 데이터가 전달되며, 사용자는 이 객체를 원하는 형태로 사용하면 됩니다.


8. VehicleDataRequest 만들기

subscribe를 호출하기전에 어썸커넥트에게 요청할 데이터 리스트를 작성해야 합니다.
SDK에서는 VehicleDataRequest 클래스를 제공하고 여기에 addDataElement를 통해 원하는 데이터를 지정하여 사용할 수 있습니다.
VehicleDataRequest 사용법은 build 패턴을 이용하여 간단히 사용할 수 있으며 예제 코드는 다음과 같습니다.


private void getVehicleData() {
	VehicleDataRequest request = new VehicleDataRequest.Builder()  
		.addDataElement(VehicleData.Diesel.soot)
		.addDataElement(VehicleData.Battery.battery_charge_current)  
		.addDataElement(VehicleData.Battery.battery_charge_remain)  
		.build();  
}

NOTE : addDataElement(VehicleData) 및 addDataElementGroup(int[])로 데이터 리스트를 추가할 수 있습니다.


9. 데이터 수신하기

VehicleDataRequest와 VehicleDataListener를 정상적으로 설치하였으면 subscribe와 start를 통해 데이터 수신을 시작할 수 있습니다. 중단은 반드시 disconnect 메서드를 이용해 중단해야 합니다. 


int[] list = new int[elementList.size()];
for(int i = 0; i < elementList.size(); i++) {
	list[i] = elementList.get(i);
}
VehicleDataRequest request = new VehicleDataRequest.Builder()
		.addDataElementGroup(list)
		.build();

this.mVehicleManager.subscribe(request, this);
this.mVehicleManager.start();
Log.d(TAG, "start VehicleManager");

NOTE : 지정되지 않은 번호의 인덱스를 addDataElement에 추가할 수는 있지만, 적합하지 않으면 어썸커넥트에서 해당 데이터는 발신하지 않습니다. 그리하여 6번항의 VehicleDataList를 얻어와서 사용하길 권장합니다.


10. 블루투스 기능 콜백 수신하기

ConnectionListener에는 onConnected(), onConnectionFailed(VPResultInfo)외에 블루투스 연결 확인을 위한 콜백도 지원합니다.
어썸커넥트앱의 블루투스 연결상태를 파악할 수 있으며, 상태 변경에 대한 콜백수신이 가능합니다. 예제 코드는 다음과 같습니다.


import android.os.Bundle;
import com.awesomeit.vehicleplus.library.api.VehicleDataListener;

public class MainActivity extends AppCompatActivity implements VehicleDataListener {
	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);  
		setContentView(R.layout.activity_main);  
	}
  
	@Override  
	public void onBluetoothConnected(VPBluetoothDeviceInfo vpBluetoothDeviceInfo) {
		// Here your application codes..  
	}  

	@Override  
	public void onBluetoothChanged(VPResultInfo vpResultInfo) {
		// Here your application codes..
	}
}

어썸커넥트에서 블루투스가 연결된 경우 onBluetoothConnected에 연결된 BluetoothDeviceInfo가 수신됩니다.
VPBluetoothDeviceInfo 클래스는 Getter 메서드로 연결된 블루투스의 MacAddress를 얻을 수 있습니다. 블루투스의 상태가 변경될 때 마다 onBluetoothChanged에 Notify가 수신됩니다.


11. 선택된 차량정보 수신하기

ConnectionListener에는 선택된 차량정보를 수신할 수 있는 콜백메서드가 존재합니다.
VehicleManager를 통해 getVehicleInfo를 호출하면, 현재 어썸커넥트에서 선택된 차량정보를 콜백메서드로 수신이 가능합니다.


import android.os.Bundle;
import com.awesomeit.vehicleplus.library.api.VehicleDataListener;

public class MainActivity extends AppCompatActivity implements VehicleDataListener {
	@Override  
	protected void onCreate(Bundle savedInstanceState) {  
		super.onCreate(savedInstanceState);  
		setContentView(R.layout.activity_main);  
	}
  
	@Override  
	public void onSelectedVehicleInfo(VPVehicleInfo vpVehicleInfo){  
		// Here your application codes..  
	}
}


12. onEventListener

ConnectionListener에서는 onEventListener(String, String) 콜백메서드도 구현해야합니다. 이 Event는 SDK의 하위호환성을 위해 생성한것으로 당장 사용되지는 않습니다.


13. 어썸커넥트앱의 기능 사용하기

  • 블루투스 설정하기
  • 차량설정하기
  • 지원 데이터 보기
  • 통신 속도 설정하기
  • 로그 보내기

인증하기까지의 초기화 작업을 정상적으로 수행하면, 이후부터는 어썸커넥트의 기능들을 사용할 수 있습니다.
어썸커넥트의 기능은 순서에 상관없이 원하는대로 사용이 가능합니다. 공개된 버전에서의 해당기능은 SDK의 코드레벨에서의 접근이 아닌, 어썸커넥트의 화면을 불러와서 기능을 수행하는 방식을 사용합니다.

NOTE : 블루투스 어댑터 설정 및 차량정보를 설정하지 않은 상태에서는 SDK의 데이터 통신이 정상적으로 작동되지 않습니다.

어썸커넥트의 화면을 불러오는 메서드는 모두 startDisplay(DisplayType) 을 이용합니다. DisplayType은 다음과 같이 정리되어 있습니다.


public class DisplayType {
	public static final int DISPLAY_VEHICLE_SETTING = 0;
	public static final int DISPLAY_SUPPORTED_VEHICLEDATA = 1;
	public static final int DISPLAY_BLUETOOTH_SETTING = 2;
}

NOTE : 이후에 업데이트 되는 버전에 따라 DisplayType의 기능은 지속적으로 추가될 예정입니다. 버전마다 다를 수 있으니 제공되는 SDK의 DisplayType을 확인하시길 바랍니다.

호출하고자 하는 화면에 따라 위의 정의된 DisplayType을 첫번째 파라미터로 전달하면 됩니다. 예제 코드는 다음과 같습니다.


public void startVehicleSettingDisplay() {
	mVehicleManager.startDisplay(DisplayType.DISPLAY_VEHICLE_SETTING);
}


14. 블루투스 설정하기

사용자의 블루투스 어댑터를 검색하고 어썸커넥트에서 사용할 블루투스 어댑터를 등록하기 위한 화면을 불러옵니다. 다음과 같이 수행합니다.


public void startBluetoothSettingDisplay() {
	mVehicleManager.startDisplay(DisplayType.DISPLAY_BLUETOOTH_SETTING);
}

위의 메서드대로 호출하면, 어썸커넥트의 블루투스 연결하기 화면이 최상위로 올라옵니다. 사용자는 사용하는 블루투스 디바이스를 검색하고 설정할 수 있습니다.

NOTE: 블루투스 디바이스는 현재 ELM327을 지원하는 디바이스만 지원됩니다. 다른 디바이스는 등록할 수 있으나 실제 통신시도시 작동하지 않습니다.


15. 차량설정하기

사용자의 차량 정보(VehicleInfo)를 설정할 수 있습니다. 어썸커넥트에서 블루투스 디바이스 설정과 차량설정까지 완료되면, SDK에서는 subscribe 메서드로 수신이 가능합니다.


public void startVehicleSettingsDisplay() {
	mVehicleManager.startDisplay(DisplayType.DISPLAY_VEHICLE_SETTING);
}


16. 지원 데이터 보기

어썸커넥트에서 설정한 차종의 지원데이터를 확인 할 수 있습니다. 지원데이터는 분류되어있으며, 원하는 데이터가 어썸커넥트에서 지원하는지 확인할 수 있습니다.


public void startSupportedVehicleDataDisplay() {
	mVehicleManager.startDisplay(DisplayType.DISPLAY_SUPPORTED_VEHICLEDATA);
}

NOTE: 데이터의 지원여부는 버전마다 다를 수 있습니다.


17. 문의하기

어썸커넥트의 문의사항 및 차량의 분석되지 않은 Raw 데이터를 어썸잇의 개발팀에게 보낼 수 있는 기능입니다.


public void startSendLogDataDisplay() {
	mVehicleManager.startDisplay(DisplayType.DISPLAY_SEND_LOG_DATA);
}


18. API 가이드

API는 모두 제공되는 SDK에서 접근이 가능합니다. API는 다음과 같이 구성되어 있습니다.

a. 패키지명

com.awesomeit.vehicleplus.library

  • com.awesomeit.vehicleplus.api
  • com.awesomeit.vehicleplus.api.constant

b. com.awesomeit.vehicleplus.api

유저 앱에 포함되어 사용할 수 있는 API들의 모음입니다.

  • VehicleManager
  • VehicleDataRequest
  • VehicleDataListener
  • ConnectionListener

c. com.awesomeit.vehicleplus.api.model

비이클 플러스의 Model 클래스들의 모음입니다. JSON anotation을 사용합니다.

  • VPBluetoothDeviceInfo
  • VPObject
  • VPResultInfo
  • VPVehicleData
  • VPVehicleDataTable
  • VPVehicleInfo

d. com.awesomeit.vehicleplus.api.constant

API를 사용하기 위해 상수로 지원되는 클래스들의 모음입니다.

  • ConnectionResult
  • DisplayType
  • VehicleDataType