파서를 사용하여 수신된 원시 데이터를 구조화된 형태로 변환할 수 있습니다.
파서 목록
파서 목록에서 등록된 파서들을 확인하고 관리할 수 있습니다.
| 항목 | 설명 |
|---|---|
| 파서 이름 | 파서의 고유 이름 |
| 설명 | 파서에 대한 설명 |
| 타임아웃 | 파서 실행 제한 시간 (ms) |
| 상태 | 활성화/비활성화 상태 |
| 수정일 | 마지막 수정 날짜 |
파서 생성
파서 생성 버튼을 클릭하여 새로운 파서를 생성합니다.
기본 정보
| 항목 | 설명 |
|---|---|
| 파서 이름 | 파서의 고유 이름 (예: HEX 센서 파서) |
| 설명 | 파서에 대한 설명 |
타임아웃 설정
타임아웃은 파서 스크립트의 최대 실행 시간을 제한합니다. 무한 루프나 과도하게 복잡한 연산으로 인해 시스템이 멈추는 것을 방지합니다.
| 항목 | 값 |
|---|---|
| 기본값 | 1000ms (1초) |
| 최소값 | 100ms |
| 최대값 | 10000ms (10초) |
파싱 실패 시 동작
타임아웃 초과 또는 스크립트 에러 발생 시:
- 파서 실행이 즉시 중단됩니다
- 원본 데이터가 그대로 저장됩니다
_parser_error필드가 추가되어 에러 메시지가 기록됩니다
| 실패 원인 | 에러 메시지 예시 |
|---|---|
| 타임아웃 | Execution timeout (1000ms) |
| 문법 에러 | SyntaxError: Unexpected token |
| 런타임 에러 | TypeError: Cannot read property 'x' of undefined |
| 참조 에러 | ReferenceError: undefinedVar is not defined |
파싱이 실패해도 원본 데이터는 보존됩니다. _parser_error 필드를 확인하여 파싱 실패 여부와 원인을 알 수 있습니다.
타임아웃 설정 가이드
- 단순 데이터 변환: 기본값 1000ms면 충분합니다
- 복잡한 연산: 필요에 따라 2000~5000ms로 설정합니다
- 대용량 데이터 처리: 최대 10000ms까지 설정 가능하나, 가급적 파서 로직을 최적화하는 것을 권장합니다
파서 스크립트 작성
파서는 JavaScript 문법을 사용합니다. parse(input) 함수를 정의하여 데이터를 변환합니다.
입력 파라미터
input.deviceId: 장치 IDinput.data: 수신된 원시 데이터
반환 값
파싱된 데이터 객체를 반환합니다. 반환된 객체의 각 필드가 저장됩니다.
내장 함수 레퍼런스
파서 스크립트에서 사용할 수 있는 내장 함수와 객체입니다.
console
디버깅을 위한 로그 출력 함수입니다. 출력 내용은 테스트 실행 시 Console 영역에 표시됩니다.
Buffer
바이너리 데이터를 파싱하기 위한 클래스입니다. Node.js의 Buffer API와 호환됩니다.
Buffer 생성
정수 읽기
| 메서드 | 설명 | 바이트 |
|---|---|---|
readUInt8(offset) | 부호 없는 8비트 정수 | 1 |
readInt8(offset) | 부호 있는 8비트 정수 | 1 |
readUInt16BE(offset) | 부호 없는 16비트 정수 (Big Endian) | 2 |
readUInt16LE(offset) | 부호 없는 16비트 정수 (Little Endian) | 2 |
readInt16BE(offset) | 부호 있는 16비트 정수 (Big Endian) | 2 |
readInt16LE(offset) | 부호 있는 16비트 정수 (Little Endian) | 2 |
readUInt32BE(offset) | 부호 없는 32비트 정수 (Big Endian) | 4 |
readUInt32LE(offset) | 부호 없는 32비트 정수 (Little Endian) | 4 |
readInt32BE(offset) | 부호 있는 32비트 정수 (Big Endian) | 4 |
readInt32LE(offset) | 부호 있는 32비트 정수 (Little Endian) | 4 |
Big Endian vs Little Endian: 바이트 순서를 나타냅니다. 센서 데이터시트를 확인하여 올바른 엔디안을 선택하세요. 대부분의 네트워크 프로토콜은 Big Endian을 사용합니다.
실수 읽기
| 메서드 | 설명 | 바이트 |
|---|---|---|
readFloatBE(offset) | 32비트 부동소수점 (Big Endian) | 4 |
readFloatLE(offset) | 32비트 부동소수점 (Little Endian) | 4 |
readDoubleBE(offset) | 64비트 부동소수점 (Big Endian) | 8 |
readDoubleLE(offset) | 64비트 부동소수점 (Little Endian) | 8 |
기타 메서드
Buffer 사용 예제
Checksum
CRC 체크섬을 계산하기 위한 유틸리티 객체입니다.
CRC16
| 파라미터 | 설명 | 기본값 |
|---|---|---|
bytes | Buffer 또는 바이트 배열 | (필수) |
poly | 다항식 | 0x1021 |
init | 초기값 | 0xFFFF |
CRC32
| 파라미터 | 설명 | 기본값 |
|---|---|---|
bytes | Buffer 또는 바이트 배열 | (필수) |
poly | 다항식 | 0xEDB88320 |
init | 초기값 | 0xFFFFFFFF |
Checksum 사용 예제
실전 예제
예제 1: 간단한 JSON 변환
수신 데이터의 필드명을 변경하고 단위를 변환합니다.
테스트 데이터:
예제 2: HEX 센서 데이터 파싱
LoRaWAN 센서에서 전송된 HEX 데이터를 파싱합니다.
테스트 데이터:
예제 3: 조건부 파싱
메시지 타입에 따라 다른 방식으로 파싱합니다.
예제 4: 커스텀 함수 활용
커스텀 함수를 사용하여 코드를 재사용합니다.
커스텀 함수 (celsiusToFahrenheit):
커스텀 함수 (parseTemperature):
파서 스크립트:
테스트 실행
스크립트 작성 후 테스트 실행 버튼으로 파서를 테스트할 수 있습니다.
파서 생성 페이지 하단에는 세 개의 영역이 있습니다:
| 영역 | 설명 |
|---|---|
| 테스트 데이터 | 파서에 입력할 테스트 JSON 데이터를 작성합니다 |
| Output | 파서 실행 결과 (반환된 객체)가 표시됩니다 |
| Console | console.log() 등의 디버깅 출력이 표시됩니다 |
테스트 방법
- 테스트 데이터 영역에 테스트할 JSON 데이터를 입력합니다
- 테스트 실행 버튼을 클릭합니다
- Output 영역에서 파싱 결과를, Console 영역에서 디버깅 로그를 확인합니다
테스트 실행은 실제 데이터를 저장하지 않습니다. 스크립트가 올바르게 동작하는지 확인하는 용도로만 사용됩니다.
커스텀 함수
커스텀 함수란?
커스텀 함수는 여러 파서에서 공통으로 사용할 수 있는 재사용 가능한 함수입니다.
왜 필요한가요?
- 코드 재사용: 동일한 변환 로직을 여러 파서에서 반복 작성할 필요 없이, 한 번 정의하고 여러 곳에서 호출할 수 있습니다
- 유지보수 용이: 변환 로직이 변경되면 커스텀 함수만 수정하면 모든 파서에 자동 반영됩니다
- 모듈화: 복잡한 파싱 로직을 작은 단위의 함수로 분리하여 관리할 수 있습니다
커스텀 함수 생성
커스텀 함수 버튼을 클릭하여 커스텀 함수 관리 페이지로 이동한 후, 함수 생성 버튼을 클릭합니다.
| 항목 | 설명 |
|---|---|
| 함수명 | 함수의 고유 이름 |
| 설명 | 함수에 대한 설명 |
함수 작성
커스텀 함수는 화살표 함수 형태로 작성합니다.
다양한 파라미터 타입
커스텀 함수는 숫자, 문자열, 객체, 배열 등 다양한 타입의 파라미터를 받을 수 있습니다.
| 파라미터 타입 | 예시 | 설명 |
|---|---|---|
| 숫자 | 25, 3.14 | 정수, 소수점 숫자 |
| 문자열 | "hello", "센서A" | 텍스트 데이터 |
| 객체 | { value: 10, unit: "°C" } | 키-값 쌍의 데이터 |
| 배열 | [1, 2, 3], ["a", "b"] | 순서가 있는 데이터 목록 |
| 불리언 | true, false | 참/거짓 값 |
파라미터 개수도 자유롭게
파서에서 커스텀 함수 사용
파서 스크립트에서 utils.{함수명}(args...) 형태로 커스텀 함수를 호출할 수 있습니다.
장치에 파서 적용
파서를 장치에 적용하는 방법은 두 가지가 있습니다.
방법 1: 장치 테이블에서 바로 설정
가장 빠른 방법입니다.
- 장치 메뉴로 이동
- 장치 목록의 파서 컬럼에서 버튼을 클릭
- 드롭다운에서 적용할 파서 선택
방법 2: 장치 편집 화면에서 설정
- 장치 메뉴로 이동
- 장치 목록에서 편집할 장치의 메뉴(⋮) 클릭
- 편집 선택
- 파서 필드에서 적용할 파서 선택
- 저장