{"id":49668491,"url":"https://github.com/libmcu/pulse-sdk","last_synced_at":"2026-05-06T18:06:48.158Z","repository":{"id":352916264,"uuid":"1217191924","full_name":"libmcu/pulse-sdk","owner":"libmcu","description":"A lightweight device metrics collection and reporting SDK for resource-constrained embedded systems","archived":false,"fork":false,"pushed_at":"2026-04-29T02:41:19.000Z","size":123,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T03:51:12.789Z","etag":null,"topics":["embedded","iot","libmcu","metrics","monitoring","observability","telemetry"],"latest_commit_sha":null,"homepage":"https://pulse.libmcu.org","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/libmcu.png","metadata":{"files":{"readme":"README.ko.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T16:29:28.000Z","updated_at":"2026-04-29T02:41:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/libmcu/pulse-sdk","commit_stats":null,"previous_names":["libmcu/pulse-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/libmcu/pulse-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libmcu%2Fpulse-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libmcu%2Fpulse-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libmcu%2Fpulse-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libmcu%2Fpulse-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/libmcu","download_url":"https://codeload.github.com/libmcu/pulse-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/libmcu%2Fpulse-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32705684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded","iot","libmcu","metrics","monitoring","observability","telemetry"],"created_at":"2026-05-06T18:06:38.498Z","updated_at":"2026-05-06T18:06:48.152Z","avatar_url":"https://github.com/libmcu.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pulse SDK\n\n[English README](README.md)\n\nPulse SDK는 [libmcu/metrics](https://github.com/libmcu/libmcu/tree/main/modules/metrics)를\n사용하여 디바이스 메트릭을 수집하고,\n이를 [Pulse](https://pulse.libmcu.org) ingest 서버로 전송합니다.\n\n## 사용 예제\n\n```c\n#include \"pulse/pulse.h\"\n\nstatic void update_metrics(void *ctx)\n{\n\tmetrics_set(SensorValue, get_your_sensor_value());\n}\n\nvoid example(void)\n{\n\tstruct pulse conf = {\n\t\t.token = \"example-token\",\n\t\t.serial_number = \"device-1234\",\n\t\t.software_version = \"1.0.0\",\n\t};\n\n\tif (pulse_init(\u0026conf) != PULSE_STATUS_OK) {\n\t\treturn;\n\t}\n\n\tpulse_set_prepare_handler(update_metrics, NULL);\n\n\tmetrics_increase(RunCount);\n\tpulse_report();\n}\n```\n\n\u003e [!NOTE]\n\u003e 인증 토큰은 [Pulse](https://pulse.libmcu.org) 의 product setup에서 생성하거나,\n\u003e 이미 발급된 토큰을 그대로 사용하면 됩니다. 준비된 토큰은 `pulse_init()` 또는\n\u003e `pulse_update_token()`으로 설정할 수 있습니다.\n\u003e `struct pulse`의 `token`, `serial_number`, `software_version`은 필수 항목입니다.\n\u003e 세 값 모두 `NULL`이 아니고 비어 있지 않은 null-terminated 문자열이어야 합니다.\n\u003e null terminator 자체는 payload에 인코딩되지 않습니다.\n\nmetrics.def 파일 예시:\n\n```c\nMETRICS_DEFINE_COUNTER(RunCount)\nMETRICS_DEFINE(SensorValue)\n```\n\n## 플랫폼별 연동 방법\n\n### HTTPS / CoAPS 선택 방법\n\nPulse SDK는 두 가지 transport를 지원합니다.\n\n- `coaps` — 기본값. CoAP over DTLS PSK 사용\n- `https` — HTTPS over TLS 사용\n\n`coaps`를 선택하면 `pulse_init()`에 전달한 token을 DTLS PSK로 재사용하고,\nDTLS PSK identity는 SDK가 내부에서 계산합니다.\n\n플랫폼별 선택 방법은 아래와 같습니다:\n\n- **Zephyr**: `prj.conf`에서 `CONFIG_PULSE_TRANSPORT_COAPS=y`(기본값) 또는\n  `CONFIG_PULSE_TRANSPORT_HTTPS=y` 선택하면 됩니다.\n- **ESP-IDF**: `menuconfig`에서 transport 선택하면 됩니다.\n- **일반 CMake / Linux**: SDK를 `add_subdirectory()` 하기 전에\n  `PULSE_TRANSPORT` 설정하면 됩니다.\n- **Baremetal Make**: 번들 Make 통합은 HTTPS transport만 자동 추가합니다.\n  CoAPS를 사용하려면 transport 소스를 수동으로 바꿔 넣어야 합니다.\n\n### Zephyr\n\nwest manifest에\n[west 모듈](https://docs.zephyrproject.org/latest/develop/modules.html)로 추가합니다.\n\n```yaml\nmanifest:\n  projects:\n    - name: pulse\n      url: https://github.com/libmcu/pulse-sdk.git\n      revision: main\n      path: modules/lib/pulse\n```\n\n`prj.conf`에서 모듈을 활성화합니다.\n\n```conf\nCONFIG_PULSE=y\nCONFIG_PULSE_TRANSPORT_COAPS=y\n#CONFIG_PULSE_TRANSPORT_HTTPS=y\n#CONFIG_PULSE_METRICS_USER_DEFINES=/path/to/metrics.def\n```\n\n\u003e [!NOTE]\n\u003e 메트릭 정의 파일 경로는 `CONFIG_PULSE_METRICS_USER_DEFINES`로 설정됩니다.\n\u003e 기본값은 `include/metrics.def` 입니다.\n\n### ESP-IDF\n\n프로젝트의 `components/` 디렉터리 아래에 SDK를 git 서브모듈로 추가하거나 클론합니다.\n\n```bash\ncd components\ngit submodule add https://github.com/libmcu/pulse-sdk.git pulse\n```\n\ntransport는 `menuconfig`에서 선택하면 됩니다.\n\n```text\nComponent config  ---\u003e\n  Pulse  ---\u003e\n    (X) CoAPS (CoAP over DTLS PSK)\n    ( ) HTTPS\n```\n\n기본값은 CoAPS입니다.\n\n\u003e [!NOTE]\n\u003e 메트릭 정의 파일 경로는 `main/metrics.def` 입니다.\n\n### 일반 CMake 프로젝트\n\nPulse SDK를 subdirectory로 추가하고 대상에 링크하시면 됩니다.\n\n```cmake\nset(METRICS_USER_DEFINES \"${CMAKE_CURRENT_SOURCE_DIR}/metrics.def\")\nset(PULSE_TRANSPORT coaps CACHE STRING \"\") # 기본값\n# set(PULSE_TRANSPORT https CACHE STRING \"\")\n\nadd_subdirectory(path/to/pulse)\ntarget_link_libraries(your_target PRIVATE pulse)\n```\n\n프로젝트 구조상 의존성 경로를 자동 탐지할 수 없으면, subdirectory 추가 전에 명시적으로 지정하면 됩니다.\n\n```cmake\nset(PULSE_LIBMCU_ROOT /path/to/libmcu)\nset(PULSE_CBOR_ROOT /path/to/cbor)\nset(METRICS_USER_DEFINES \"${CMAKE_CURRENT_SOURCE_DIR}/metrics.def\")\n\nadd_subdirectory(path/to/pulse)\ntarget_link_libraries(your_target PRIVATE pulse)\n```\n\n애플리케이션이 이미 `libmcu`를 자체 방식으로 빌드/링크하고 있다면 그대로 유지하면 됩니다.\nPulse SDK는 `libmcu`를 public 의존성으로 사용하고, `cbor`는 SDK 내부 구현 의존성으로만 사용합니다.\n\n애플리케이션이 `retry`, `ratelim` 같은 일반 `libmcu` 모듈도 함께 쓰고 싶다면,\n다른 `libmcu` 복사본을 하나 더 clone해서 링크하지 말고 Pulse SDK가 resolve한\n같은 dependency target을 재사용하는 쪽을 권장합니다.\n\n```cmake\ntarget_link_libraries(your_target PRIVATE\n\tpulse\n\tpulse::libmcu)\n```\n\n### Linux\n\nLinux에서는 `pulse_collect()`가 아래 파일을 추가합니다.\n\n- `ports/linux/pulse_overrides.c`\n- `ports/linux/pulse_transport_\u003ctransport\u003e.c`\n\n기본 통합 방법은 일반 CMake와 동일합니다.\n\n```cmake\nset(METRICS_USER_DEFINES \"${CMAKE_CURRENT_SOURCE_DIR}/metrics.def\")\nset(PULSE_TRANSPORT coaps CACHE STRING \"\") # 기본값\n# set(PULSE_TRANSPORT https CACHE STRING \"\")\n\nadd_subdirectory(path/to/pulse)\nadd_executable(app main.c)\ntarget_link_libraries(app PRIVATE pulse)\n```\n\n### Baremetal\n\nMake 기반 baremetal 프로젝트에서는 `pulse.mk`를 include한 뒤, export되는 소스 목록과 include 경로를 애플리케이션 빌드 변수에 추가하시면 됩니다.\n\n```make\nPULSE_ROOT ?= path/to/pulse\nLIBMCU_ROOT ?= path/to/libmcu\nCBOR_ROOT ?= path/to/cbor\n\ninclude $(PULSE_ROOT)/pulse.mk\n\nAPP_SRCS += $(PULSE_SRCS)\nAPP_INCS += $(PULSE_INCS)\n# LDFLAGS += $(PULSE_LDFLAGS)  # only needed if you archive Pulse SDK separately\n```\n\n`LIBMCU_ROOT`가 `$(PULSE_ROOT)/external/libmcu`로 해석되면, Make 통합은 아래 항목도 함께 포함합니다.\n\n- `ports/baremetal/pulse_overrides.c`\n- `ports/baremetal/pulse_transport_https.c`\n- bundled `libmcu` metrics 관련 필수 소스\n\n이미 프로젝트에서 cbor을 별도로 빌드하고 있다면, `PULSE_SRCS` 대신\n`PULSE_CORE_SRCS`를 사용하도록 변경하세요\n이렇게 하면 기존의 cbor 관리 방식을 그대로 유지할 수 있습니다.\n\n```make\nAPP_SRCS += $(PULSE_CORE_SRCS)\nAPP_SRCS += $(YOUR_CBOR_SRCS)\nAPP_INCS += $(PULSE_INCS)\n```\n\nBaremetal Make 통합을 CoAPS로 바꾸려면,\n`ports/baremetal/pulse_transport_https.c` 대신\n`ports/baremetal/pulse_transport_coaps.c`를 빌드에 직접 추가하면 됩니다.\n\n## 메트릭 API\n### 메트릭 정의 매크로\n\n- `METRICS_DEFINE_COUNTER(name)`\n  - 단조 증가 정수입니다. 이벤트 횟수 기록에 사용합니다.\n- `METRICS_DEFINE_GAUGE(name, min, max)`\n  - 범위가 있는 수치입니다. min과 max를 지정합니다.\n- `METRICS_DEFINE_PERCENTAGE(name)`\n  - 0~100 범위의 정수입니다.\n- `METRICS_DEFINE_TIMER(name, unit)`\n  - 시간 지속값입니다. 단위: s, ms.\n- `METRICS_DEFINE_STATE(name)`\n  - 이산 상태 코드입니다.\n- `METRICS_DEFINE_BINARY(name)`\n  - 이진 플래그로, 0 또는 1입니다.\n- `METRICS_DEFINE_BYTES(name)`\n  - 바이트 수입니다.\n- `METRICS_DEFINE(name)`\n  - 의미론적 제약이 없는 원시 수치입니다.\n\n### 메트릭 설정 API\n\n- `metrics_set(name, val)`\n  - 메트릭 값을 설정합니다.\n- `metrics_increase(name)`\n  - 카운터를 1 증가시킵니다.\n- `metrics_increase_by(name, val)`\n  - 카운터를 지정한 값만큼 증가시킵니다.\n- `metrics_reset(name)`\n  - 메트릭을 초기값으로 초기화합니다.\n\n## 참고\n\nPulse SDK는 [libmcu](https://github.com/libmcu/libmcu)와\n[cbor](https://github.com/libmcu/cbor)에 의존합니다.\n\n- `libmcu`는 public 의존성임. `pulse/pulse.h`가 libmcu metrics 타입을 노출하고,\n  애플리케이션도 `metrics_*()` API를 직접 호출하는 사용 방식을 전제로 함.\n- `cbor`는 internal 의존성임. Pulse SDK가 private하게 빌드에 포함하며 public API로 노출하지 않음.\n\nCMake 통합 시 의존성 루트는 아래 순서로 해석됩니다.\n\n1. `PULSE_LIBMCU_ROOT` / `PULSE_CBOR_ROOT`\n2. `LIBMCU_ROOT` / `CBOR_ROOT`\n3. `external/libmcu` / `external/cbor`\n4. CMake fetch 폴백\n\nMake 통합 시 `pulse.mk`는 아래 순서로 의존성을 해석합니다.\n\n1. `PULSE_LIBMCU_ROOT` / `PULSE_CBOR_ROOT`\n2. `LIBMCU_ROOT` / `CBOR_ROOT`\n3. `external/libmcu` / `external/cbor`\n\n애플리케이션은 필수 Pulse 메타데이터를 `struct pulse`로 직접 제공해야 합니다.\n\n- `token`\n- `serial_number`\n- `software_version`\n\n\u003e [!IMPORTANT]\n\u003e `PULSE_LIBMCU_ROOT` 또는 `LIBMCU_ROOT`가 외부 libmcu 루트\n\u003e (번들 `external/libmcu`가 아닌 경로)를 가리키는 경우에도,\n\u003e `pulse_collect()`는 Pulse SDK 소유 플랫폼 오버라이드 및 전송 모듈은 자동 추가함.\n\u003e 사용자는 아래 libmcu 구현이 최종 애플리케이션에 링크되도록만 보장하면 됨.\n\u003e 기존 libmcu target/library를 그대로 써도 되고, 필요 시 아래 소스를 직접 추가해도 됨.\n\u003e\n\u003e - `\u003clibmcu\u003e/modules/metrics/src/metrics.c`\n\u003e - `\u003clibmcu\u003e/modules/metrics/src/metricfs.c`\n\u003e - `\u003clibmcu\u003e/modules/common/src/assert.c`\n\u003e - `\u003clibmcu\u003e/modules/common/src/base64.c` (`PULSE_TRANSPORT=coaps` 사용 시)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibmcu%2Fpulse-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flibmcu%2Fpulse-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flibmcu%2Fpulse-sdk/lists"}