본문으로 건너뛰기

화면 캡처 - Use Cases

CSMS는 충전기 HMI의 특정 화면이 표시되는 순간을 자동으로 캡처하여 서버로 전송하도록 요청할 수 있습니다. 이를 통해 관리자는 원격으로 충전기 화면 상태를 사후 검증할 수 있습니다.

OCPP v1.6/v2.1 공통

화면 캡처 기능은 SK일렉링크 커스텀 DataTransfer 메시지로 동작합니다. OCPP v1.6과 OCPP v2.1 세션 모두 DataTransfer:com.skelectlink:TriggerScreenCapture, DataTransfer:com.skelectlink:ScreenCaptureResult를 사용합니다.

개요​

동작 방식: 이벤트 기반 자동 스냅샷​

본 기능은 "예약형 스냅샷 요청" 방식으로 동작합니다.

  1. 관리자: 어드민에서 특정 충전기에 관심 화면 ID(예: SCR_ERROR_01)를 지정하여 캡처 트리거를 설정합니다.
  2. 충전기: 평소에는 대기하다가, 내부 로직에 의해 해당 화면 ID가 렌더링되는 순간을 포착합니다.
  3. 실행: 해당 화면이 감지되면 즉시 화면을 캡처하고, CSMS가 제공한 업로드 URL로 HTTP POST(multipart) 전송합니다.
  4. 결과 보고: 업로드 완료 후 ScreenCaptureResult DataTransfer로 메타데이터를 CSMS에 전송합니다.
  5. 확인: 관리자는 어드민에서 캡처된 이미지를 사후 확인합니다.

캡처 트리거 설정​

CSMS가 EVSE에 특정 화면 ID의 캡처 트리거를 설정합니다. EVSE는 해당 화면이 렌더링되는 순간을 감지하여 캡처를 수행합니다.

  1. CSMS: DataTransfer:com.skelectlink:TriggerScreenCapture 전송 (업로드 URL 포함)
  2. EVSE: 트리거 등록 가능 여부를 즉시 응답 (Accepted/Rejected)
  3. EVSE: 이후 해당 화면 감지 시 캡처 수행 → HTTP POST(multipart) 업로드 → ScreenCaptureResult로 메타데이터 전송

요청​

예시
[
  2,
  "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "DataTransfer",
  {
    "vendorId": "com.skelectlink",
    "messageId": "TriggerScreenCapture",
    "data": {
      "screenId": "SCR_ERROR_01",
      "expireAt": "2025-04-07T09:00:00Z",
      "maxCaptures": 3,
      "uploadUrl": "https://csms.example.com/v1/screen-capture/60130038-01/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
]

요청 필드​

Field NameTypeRequiredDescription
screenIdStringRequired캡처 대상 화면 식별자 (충전기 내부 화면 ID). 예약어 *는 "즉시 캡처"를 의미합니다 (아래 참고).
expireAtDateTimeRequired트리거 유효 만료 시각 (UTC, ISO 8601). 이 시각이 지나면 트리거를 자동 해제합니다.
maxCapturesNumberOptional최대 캡처 횟수. 생략 시 기본값 1. 해당 횟수 도달 시 트리거 자동 해제.
uploadUrlStringRequired캡처 이미지를 HTTP POST(multipart)로 업로드할 URL.
업로드 URL

EVSE는 캡처 시마다 이 URL에 HTTP POST(multipart)로 이미지를 업로드합니다. 서버는 maxCaptures 횟수까지만 업로드를 수락하며, 도달 시 이후 업로드 요청은 거부(HTTP 409)됩니다. EVSE는 maxCaptures에 도달하면 해당 트리거를 자동 해제해야 합니다.

즉시 캡처: screenId="*" 예약어

현재 표시 중인 화면을 지금 바로 확인해야 할 때 사용하는 예약된 화면 식별자입니다. EVSE는 screenId가 *인 트리거를 받으면 렌더링 이벤트를 기다리지 않고 요청 수신 즉시 현재 화면을 1회 캡처하여 uploadUrl로 업로드하고 트리거를 자동 해제합니다. CSMS는 이 예약어를 정규 화면 ID로 정의하지 않으며, 서버 측에서는 maxCaptures=1로 정규화됩니다.

응답​

예시
[
  3,
  "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  {
    "data": {
      "status": "Accepted"
    },
    "status": "Accepted"
  }
]

응답 필드​

Field NameTypeRequiredDescription
statusTriggerScreenCaptureStatusEnumTypeRequired트리거 등록 결과 상태
statusInfoStatusInfoTypeOptional상세 상태 정보

TriggerScreenCaptureStatusEnumType:

ValueDescription
Accepted트리거가 정상적으로 등록되었습니다.
Rejected트리거 등록이 거부되었습니다 (지원하지 않는 screenId 등).
NotSupported충전기가 화면 캡처 기능을 지원하지 않습니다.

캡처 결과 전송​

EVSE가 트리거된 화면을 감지하여 캡처를 완료한 후, HTTP로 이미지를 업로드하고 메타데이터를 CSMS로 전송합니다.

  1. EVSE: 등록된 screenId의 화면이 렌더링되는 순간을 감지
  2. EVSE: 화면 캡처 수행
  3. EVSE: uploadUrl로 이미지 HTTP POST(multipart) 업로드
  4. EVSE: DataTransfer:com.skelectlink:ScreenCaptureResult 전송 (메타데이터)
  5. CSMS: 메타데이터 저장 후 응답

요청​

예시
[
  2,
  "b914adcc-d113-46de-ad4b-edb168b96045",
  "DataTransfer",
  {
    "vendorId": "com.skelectlink",
    "messageId": "ScreenCaptureResult",
    "data": {
      "screenId": "SCR_ERROR_01",
      "capturedAt": "2025-04-06T14:23:15Z",
      "uploadStatus": "Uploaded"
    }
  }
]

요청 필드​

Field NameTypeRequiredDescription
screenIdStringRequired캡처된 화면의 식별자 (트리거 설정 시 지정한 값)
capturedAtDateTimeRequired실제 캡처가 수행된 시각 (UTC, ISO 8601)
uploadStatusStringRequiredHTTP 업로드 결과 (Uploaded, UploadFailed)
업로드 실패 시

uploadStatus가 UploadFailed인 경우, EVSE는 최대 3회까지 재시도합니다. 재시도 모두 실패 시 UploadFailed 상태로 ScreenCaptureResult를 전송하여 CSMS에 실패를 알립니다.

응답​

예시
[
  3,
  "b914adcc-d113-46de-ad4b-edb168b96045",
  {
    "status": "Accepted"
  }
]

전체 연동 흐름​

EVSE 구현 권장사항​

  1. 트리거 저장: TriggerScreenCapture 수신 시 screenId, expireAt, uploadUrl을 내부 메모리에 저장합니다. 단, screenId="*"인 경우 저장 없이 즉시 캡처 단계로 진행합니다.
  2. 화면 감시: 등록된 screenId가 렌더링 엔진에 의해 활성화되는 순간을 이벤트 리스너로 감지합니다.
  3. 캡처 실행: 감지 즉시(또는 screenId="*"인 경우 요청 수신 즉시) 현재 화면을 캡처합니다.
  4. HTTP 업로드: 캡처된 이미지를 uploadUrl로 HTTP POST(multipart) 전송합니다. Content-Type은 multipart/form-data로 설정하고, 이미지는 file 파트에 포함합니다.
  5. 결과 보고: 업로드 성공/실패 여부를 ScreenCaptureResult DataTransfer로 CSMS에 전송합니다.
  6. 유효 기간 관리: expireAt 시각이 경과한 트리거는 자동으로 해제하여 메모리를 확보합니다.
  7. 중복 방지: 동일한 screenId에 대해 새로운 트리거가 도착하면 기존 트리거를 교체합니다.
  8. 캡처 횟수: maxCaptures 값에 따라 캡처 횟수를 제한합니다. 생략된 경우 기본값 1로 동작하며, 지정된 횟수만큼 캡처를 완료하면 해당 트리거를 자동 해제합니다.
  9. 이미지 최적화: 네트워크 트래픽 절감을 위해 JPEG 포맷, 품질 80% 이하를 권장합니다.
  10. 업로드 재시도: HTTP 업로드 실패 시 최대 3회 재시도합니다. 모든 재시도 실패 시 UploadFailed 상태로 결과를 보고합니다.
  11. 오프라인 처리: 캡처 시점에 네트워크가 불가한 경우, 이미지를 로컬에 임시 저장하고 재연결 후 업로드합니다. 단, 캡처 후 1시간 이상 전송하지 못한 경우 해당 캡처는 폐기합니다.