nRF 예제 코드¶

참고: 이 문서는 레거시 C 참조 예제이다. 신규 개발에는 Rust SDK 예제와 Rust SDK를 사용한다.

Nordic Semiconductor nRF 플랫폼에서 Xylolabs API를 사용하기 위한 C 예제 코드이다.

파일 구조¶

File	Description
`nrf52840_ble_example.c`	nRF52840 BLE 센서 비콘 (XMBP 인코딩, 초저전력 슬립)

설계 원칙¶

Zephyr RTOS¶

모든 예제는 Zephyr RTOS 기반의 nRF Connect SDK를 사용한다. Zephyr는 nRF 디바이스 전반에 걸쳐 GPIO, I2C, SPI, BLE, 전원 관리를 위한 이식 가능한 추상화 레이어를 제공한다.

// Zephyr 디바이스 트리 바인딩 (레지스터 직접 접근보다 권장)
static const struct device *accel = DEVICE_DT_GET(DT_NODELABEL(lis2dh));
static const struct device *temp  = DEVICE_DT_GET(DT_NODELABEL(hts221));

// Zephyr 센서 API
sensor_sample_fetch(accel);
sensor_channel_get(accel, SENSOR_CHAN_ACCEL_XYZ, &accel_val);

BLE GATT 알림¶

nRF52840 예제는 BLE 페리퍼럴로 동작한다. 커스텀 GATT 서비스를 광고하고, XMBP로 인코딩된 센서 데이터를 BLE 알림으로 연결된 게이트웨이(라즈베리 파이, 스마트폰, nRF9160 게이트웨이 등)에 전송한다.

nRF52840 (센서) --[BLE GATT notify]--> 게이트웨이 --[LTE/WiFi]--> api.xylolabs.com

게이트웨이는 XMBP 바이너리 페이로드를 Xylolabs HTTP API로 포워딩할 책임이 있다. XMBP 형식은 변환 없이 그대로 전달된다.

초저전력¶

nRF52840은 배터리 구동 환경을 목표로 한다. BLE 전송 사이에 디바이스는 System OFF 또는 System ON(라이트 슬립) 모드로 진입한다.

광고 간격: 1000 ms (듀티 사이클 감소)
연결 간격: 200 ms (최소 지원: 7.5 ms)
System ON 슬립: 센서 읽기 사이에 k_sleep(K_MSEC(SAMPLE_INTERVAL_MS)) 사용
RTC 웨이크업: Zephyr k_timer가 메인 CPU 클럭 대신 32.768 kHz LFXO를 사용

일반적인 소비 전류: 슬립 시 약 5 µA, BLE TX 시 약 6 mA.

XAP 2ch@48kHz 지원 가능¶

nRF52840(Cortex-M4F, 256KB RAM)은 XAP(LC3 기반) 2채널 / 48 kHz / 채널당 64 kbps 인코딩이 가능하다. 그러나 BLE GATT 알림 MTU(알림당 최대 247바이트)가 처리량을 제한한다. 오디오 사용 사례에는 직접 LTE-M1을 사용하는 nRF9160 타겟을 권장한다.

BLE 센서 비콘 예제는 배터리 구동 BLE 노드의 주요 사용 사례인 센서 데이터(가속도계, 온도)에 초점을 맞춥니다.

레거시 C 빌드¶

이 예제들은 nRF Connect SDK와 west 빌드 도구를 사용한다. nRF Connect SDK v2.x에서 테스트되었는다.

# nRF Connect SDK 워크스페이스 초기화 (최초 1회)
west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.6.0 nrf-workspace
cd nrf-workspace
west update

# nRF52840 DK용 빌드
west build -b nrf52840dk_nrf52840 docs/examples/nrf/

# 플래시
west flash

# 시리얼 출력 모니터링
screen /dev/ttyACM0 115200

prj.conf (최소 Kconfig)¶

CONFIG_BT=y
CONFIG_BT_PERIPHERAL=y
CONFIG_BT_GATT_DYNAMIC_DB=y
CONFIG_BT_DEVICE_NAME="XyloSensor"
CONFIG_SENSOR=y
CONFIG_WDT=y
CONFIG_PM=y
CONFIG_PM_DEVICE=y

CMakeLists.txt¶

cmake_minimum_required(VERSION 3.20)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(xylolabs_nrf52840_example)

target_sources(app PRIVATE nrf52840_ble_example.c)
target_include_directories(app PRIVATE
    ${CMAKE_SOURCE_DIR}/../../../sdk/c/common/include
    ${CMAKE_SOURCE_DIR}/../../../sdk/c/nrf
)

BLE 게이트웨이 레퍼런스¶

BLE 게이트웨이는 BLE GATT를 통해 XMBP 바이너리 페이로드를 수신하고, HTTP POST로 Xylolabs API에 포워딩한다.

# Python 게이트웨이 예제 (bleak 사용)
import asyncio, httpx
from bleak import BleakClient

XYLOLABS_API = "https://api.xylolabs.com/api/v1/ingest"
API_KEY = "xk_your_api_key_here"
XMBP_NOTIFY_UUID = "12345678-1234-1234-1234-1234567890ab"

async def on_notify(sender, data: bytearray):
    async with httpx.AsyncClient() as client:
        await client.post(XYLOLABS_API,
            content=bytes(data),
            headers={"X-Api-Key": API_KEY,
                     "Content-Type": "application/octet-stream"})

async def main():
    async with BleakClient("AA:BB:CC:DD:EE:FF") as client:
        await client.start_notify(XMBP_NOTIFY_UUID, on_notify)
        await asyncio.sleep(3600)

asyncio.run(main())

API 문서 참고¶

API Reference -- XMBP 프로토콜, 수집 세션, 오디오 업로드, API 키 관리, 장치 관리