LoRa 패킷 하나를 보냈다고 LoRaWAN 메시지가 되는 것은 아니다

1. 같은 라디오를 써도 계약이 다르다

LoRa는 CSS 변조를 쓰는 무선 PHY다. <zephyr/drivers/lora.h>의 lora_config()·lora_send()·lora_recv()는 라디오 장치의 직접 패킷 송수신 계약이다. 반면 <zephyr/lorawan/lorawan.h>의 lorawan_start()·lorawan_join()·lorawan_send()는 LoRaWAN 네트워크에 참여한 종단 장치의 계약이다. gateway가 raw LoRa 패킷을 받았다고 해서 LoRaWAN 가입이나 애플리케이션 전달이 성립한 것은 아니다.

근거: Zephyr 3.7.0 LoRa·LoRaWAN 개요와 API.

2. 직접 LoRa는 먼저 모뎀 설정을 맞춘다

struct lora_modem_config는 Hz 단위 frequency, bandwidth, datarate(SF), coding_rate, preamble, 출력 전력, tx 방향, IQ 반전과 public/private sync 설정을 담는다. 다른 보드의 raw LoRa 패킷을 받으려면 양쪽 설정과 하드웨어 대역이 호환돼야 한다. 3.7.0의 수신 예시는 DT_ALIAS(lora0)로 장치를 가져오므로, 모든 보드에 그 alias가 있다는 뜻은 아니다.

직접 링크의 sync 선택. 3.7.0 문서는 peer-to-peer 사용에서 private sync를 보통 권하고, public sync는 고급 용도로 설명한다. public_network=true만 설정해서 raw 전송을 LoRaWAN 프레임으로 바꿀 수는 없다.

근거: 3.7.0 LoRa PHY API와 modem config, 3.7.0 수신 예시의 보드·alias 조건.

3. LoRaWAN은 지역과 장치 등록을 먼저 맞춘다

LoRaWAN 경로에는 라디오뿐 아니라 network server에 등록한 장치 식별자와 키가 필요하다. 3.7.0 Kconfig의 지역 심벌은 CONFIG_LORAMAC_REGION_KR920, CONFIG_LORAMAC_REGION_EU868처럼 LORAMAC_REGION 접두사를 쓴다. enum LORAWAN_REGION_KR920 같은 런타임 지역 선택자는 별개다. 한 지역만 빌드에 넣었다면 lorawan_set_region() 호출은 필수가 아니며, 여러 지역을 넣었다면 lorawan_start() 전에 원하는 지역을 선택한다. 실제 지역·채널 계획은 사용 국가, 모듈과 네트워크 서버 설정에 맞춰 확인해야 한다.

예시와 제품의 차이. 3.7.0 Class A 샘플은 이해를 돕기 위해 EUI·키 배열과 dev_nonce=0을 코드에 넣는다. 공식 3.7.0 API 문서는 LoRaWAN 1.0.4부터 같은 EUI의 OTAA DevNonce가 단조 증가해야 하며 애플리케이션이 비휘발성 저장소에 보관해야 한다고 명시한다. 샘플 값을 제품 등록 정보로 복사하지 않는다.

근거: 3.7.0 Kconfig 지역 목록, 3.7.0 OTAA 구조체와 지역 API, v3.7.0 Class A 샘플 소스.

4. OTAA는 region → start → join 순서로 읽는다

Class A 샘플은 라디오 device_is_ready()를 먼저 검사하고, 빌드한 지역에 따라 필요하면 lorawan_set_region()을 호출한다. 그다음 lorawan_start()로 스택을 시작하고 lorawan_register_downlink_callback()과 별도의 lorawan_register_dr_changed_callback()을 등록한다. 이어 struct lorawan_join_config의 mode=LORAWAN_ACT_OTAA와 EUI·키·nonce를 채워 lorawan_join()한다. join 성공 전에 주기 uplink를 보내는 순서로 바꾸지 않는다. ABP 구조체도 API에 있지만 이 도식은 OTAA 경로만 그린다.

근거: 3.7.0 Class A 예시 안내, 태그 고정 예시의 호출 순서, 3.7.0 LoRaWAN API.

5. uplink 뒤 Class A 수신 창이 열린다

lorawan_send(port, data, len, type)는 가입된 네트워크에 uplink를 보낸다. payload가 있으면 port를 설정해야 하며, C 인자 len의 상한 255바이트가 실제 전송 가능 payload라는 뜻은 아니다. 지역·data rate·MAC 명령에 따라 다음 패킷의 허용 길이가 작아질 수 있으므로 lorawan_get_payload_sizes()를 확인한다. LORAWAN_MSG_CONFIRMED는 네트워크 ACK를 요구하지만 애플리케이션 처리 완료 증명으로 해석하지 않는다.

이 수신창 도식은 Class A에 한정된다. Class A에서는 각 uplink 뒤 RX1과, 필요하면 RX2 수신 기회가 온다. 따라서 Class A 서버의 downlink를 즉시 임의 시간에 밀어 넣는 통로로 상상하면 안 된다. RX1에 대상 패킷이 들어오면 RX2를 열 필요가 없고, 실제 window 시간·주파수·data rate는 선택한 지역 설정과 네트워크가 좌우한다.

3.7.0 API에는 LORAWAN_CLASS_C와 lorawan_set_class()도 있다. Class C로 전환해 지원 구성에서 호출이 성공하면, 장치는 송신과 RX1·RX2 처리 시간을 제외하고 RXC 수신을 지속한다. 따라서 모든 클래스의 downlink가 다음 uplink에만 묶인다고 일반화할 수 없다. Class C는 수신기의 가동 시간과 전력 조건도 따로 검토해야 한다.

callback은 짧게. 3.7.0 문서는 downlink callback이 system workqueue에서 실행된다고 명시한다. callback에서 긴 처리나 대기를 하지 말고 필요한 데이터를 복사해 별도 작업으로 넘긴다. 또한 3.7.0의 두 번째 인자는 bool data_pending이다. 최신 헤더의 flags 비트 해석을 그대로 가져오면 함수 시그니처가 맞지 않는다.

근거: 3.7.0 send·callback·payload 크기, 3.7.0 DR callback·Class C enum·set_class API, LoRa Alliance 1.0.4 Class A RX1/RX2·Class C RXC.

6. 한 번에 한 층씩 확인한다

보드가 준비되지 않았다면 서버 설정을 바꿔도 소용없다. 반대로 raw LoRa의 수신 RSSI가 찍힌다고 네트워크 키가 맞는 것은 아니다. 실패 지점을 아래 순서로 좁히고, 각 단계의 로그·설정·서버 이벤트를 같은 시험 시각으로 맞춘다.

근거: 3.7.0 raw LoRa 송수신 예시, 3.7.0 Class A 예시, 3.7.0 API 계약.

7. 고정 버전 근거와 적용 범위

API·구조체·설정 심벌은 아래 3.7.0 문서와 태그 고정 샘플에서 확인했다. LoRa Alliance 문서는 Class A의 RX1/RX2와 Class C의 RXC 수신 창 근거로만 사용했다. 특정 라디오 모듈·국가의 송신 허가, 링크 거리, 소비전류, gateway 호환성은 이 문서만으로 보장하지 않는다. 실제 제품은 사용 지역의 주파수 규정과 보드 드라이버·네트워크 서버 설정을 별도 검증해야 한다.

• Zephyr v3.7.0 LoRa and LoRaWAN 개요·API·Kconfig
• Zephyr v3.7.0 LoRaWAN Doxygen API
• Zephyr v3.7.0 Class A 예시 원본
• Zephyr v3.7.0 직접 LoRa 수신 예시
• LoRa Alliance LoRaWAN L2 1.0.4 규격