직렬 포트 구성

이 가이드는 PDComm Modbus SDK로 직렬 포트를 열 때 필요한 설정과 환경을 정리합니다. 개념은 직렬 회선: RTU와 ASCII, 실습은 RTU와 ASCII 통신을 봅니다.

구성 필드

필드	값	설명
`transport`	`rtu`, `ascii`	데이터 비트는 RTU 8, ASCII 7로 자동입니다.
`role`	`client`, `server`, `gateway`	게이트웨이는 TCP 쪽 `address`도 씁니다.
`port`	장치 경로	비어 있으면 `connect`가 `InvalidConfig`로 실패합니다.
`baud`	1 이상	장비와 같게 합니다. 명세 기본값은 19200입니다.
`parity`	`even`, `odd`, `none`	기본 `even`. `none`이면 `stop_bits`는 2여야 합니다.
`stop_bits`	1, 2
`unit`	1~247	서버는 자기 주소, 클라이언트는 기본 대상 주소
`timeout_ms`	1~60000	클라이언트가 응답 전체를 기다리는 시간
`ascii_timeout_ms`	1~60000, 기본 1000	ASCII 문자 사이 최대 간격
`turnaround_ms`	0~60000, 기본 100	브로드캐스트 뒤 다음 요청까지 기다리는 시간

허용되는 문자 형식은 RTU가 8E1, 8O1, 8N2, ASCII가 7E1, 7O1, 7N2입니다. 패리티 없음에 정지 비트 1은 Invalid endpoint configuration입니다. 흐름 제어는 쓰지 않습니다.

포트 이름

OS	이름 예	참고
Windows	`COM3`	장치 관리자의 “포트(COM & LPT)“에 보이는 이름
macOS	`/dev/cu.usbserial-FT1234`	장치마다 `tty.`와 `cu.` 두 이름이 있습니다. 발신 측 장치인 `cu.` 이름을 씁니다.
Linux	`/dev/ttyUSB0`, `/dev/ttyACM0`, `/dev/ttyS0`	사용자에게 `dialout` 그룹 권한이 필요합니다.

{"action":"serial_ports"}는 운영체제가 아는 직렬 장치 목록을 돌려줍니다. 어댑터를 꽂기 전과 뒤의 목록을 비교하면 이름을 찾기 쉽습니다.

{"ok":true,"result":{"ports":["/dev/cu.Bluetooth-Incoming-Port","/dev/tty.Bluetooth-Incoming-Port","/dev/cu.usbserial-FTAJM0FK","/dev/tty.usbserial-FTAJM0FK"]}}

포트는 독점으로 엽니다. 다른 프로그램(다른 PDComm 프로세스 포함)이 이미 열어 둔 포트는 connect가 Io(Other, "Unable to acquire exclusive lock on serial port")로 실패합니다. 같은 포트를 서버와 클라이언트가 함께 열 수 없습니다.

PDComm 가상 시리얼 포트

실제 케이블 없이 직렬 통신을 시험하려면 PDComm 가상 시리얼 도구를 씁니다. 설치와 구성 방법은 도구에서 안내합니다.

빠른 쌍: pdcomm-vserial pair --link-a <경로> --link-b <경로>는 널 모뎀으로 이은 의사 터미널(pseudo terminal) 두 개를 만들고 지정한 경로에 링크를 둡니다. macOS와 Linux에서 씁니다. port에 링크 경로를 지정합니다.
드라이버 포트: 가상 시리얼 드라이버가 만든 포트는 실제 포트처럼 serial_ports 목록에 나타납니다.
결함 주입: 실행 중인 가상 연결에 {"command":"inject","node":"a","fault":{"xor":1}}처럼 문자 손상을 넣어 CRC 오류를 재현합니다.

가상 포트를 쓸 때 알아 둘 점은 다음과 같습니다.

의사 터미널에는 UART가 없습니다. macOS에서 PDComm은 의사 터미널을 열 때 속도를 설정하지 않으며, 가상 연결 쪽에 설정된 속도가 적용됩니다. 패리티와 정지 비트는 적용됩니다.
가상 연결은 connect에서 설정한 형식을 그 뒤의 첫 데이터부터 적용합니다. connect 직후 바로 첫 요청을 보내도 됩니다.
장비 수락 시험은 실제 배선과 장비로 진행합니다.

USB-직렬 어댑터

지연 타이머: USB 어댑터는 받은 바이트를 묶어 넘깁니다. FTDI 어댑터의 기본 지연 타이머는 16ms이며, 측정한 응답 시간에 이 지연이 더해집니다. PDComm 클라이언트는 응답을 기능 코드로 정해지는 길이와 CRC로 완성하므로 묶음 전달 때문에 응답을 버리지 않습니다.
시각 기록: trace의 직렬 기록 시각은 PC가 읽기를 마친 시각(host_io_batch)입니다. UART의 문자 간격(t1.5, t3.5)을 증명하지 않습니다.
macOS FTDI 드라이버: macOS 기본 FTDI 드라이버는 패리티 오류를 운영체제에 알리지 않습니다. 패리티가 맞지 않는 바이트도 그대로 전달되며, 손상된 프레임은 CRC 검사가 거릅니다.
RS-485 방향 전환: 2선식 RS-485는 송신할 때만 드라이버를 켭니다. 대부분의 USB-RS485 어댑터가 자동으로 전환합니다. PDComm은 RTS를 직접 바꾸지 않습니다.

배선

연결	확인할 점
RS-232	송신과 수신이 경로 전체에서 정확히 한 번 엇갈려야 합니다. 9핀 DTE끼리는 2↔3, 3↔2, 5↔5 널 모뎀입니다. 엇갈림이 없거나 두 번이면 응답이 전혀 오지 않습니다.
RS-485 2선식	D0/D1(A/B) 극성, 버스 양 끝의 종단, 한 곳의 바이어스, 공통선(Common)을 장비 지침대로 연결합니다. 제조사마다 A/B 표기가 반대일 수 있습니다.
RS-232 ↔ RS-485	직접 연결할 수 없습니다. 변환기를 씁니다.

시간 제한 값 정하기

timeout_ms는 요청 전송, 장비의 처리, 응답 수신을 모두 포함해야 합니다. 응답이 긴 요청일수록 크게 잡습니다.

예	계산
9600bps, 8E1, 보유 레지스터 125개 읽기	응답 255바이트 × 11비트 ÷ 9600 ≈ 292ms에 요청 전송, 장비 처리, USB 지연을 더합니다.
19200bps, 8E1, 레지스터 1개	응답 7바이트 ≈ 4ms. 대부분 장비 처리 시간이 지배합니다.

장비 매뉴얼의 응답 시간에 여유를 두어 정합니다. 보통 수백 ms에서 1초입니다.
게이트웨이 뒤의 장비라면 TCP 클라이언트의 timeout_ms를 게이트웨이의 직렬 대기 시간보다 길게 합니다.
브로드캐스트를 쓴다면 turnaround_ms를 버스의 가장 느린 장비가 쓰기를 처리하는 시간보다 길게 합니다. 명세는 보통 100~200ms를 예로 듭니다.

다음 단계

응답이 오지 않거나 CRC 오류가 나면 직렬 통신 문제를 따릅니다.
구성 필드 전체는 JSON 명령 레퍼런스에 있습니다.