uploaded 1 month ago
Memfault SDK for embedded systems. Observability, logging, crash reporting, and OTA all in one service

readme

# Memfault Firmware SDK

[![CircleCI](https://circleci.com/gh/memfault/memfault-firmware-sdk.svg?style=svg)](https://circleci.com/gh/memfault/memfault-firmware-sdk)
[![Coverage](https://img.shields.io/codecov/c/gh/memfault/memfault-firmware-sdk/master)](https://codecov.io/gh/memfault/memfault-firmware-sdk/)

Ship Firmware with Confidence.

More details about the Memfault platform itself, how it works, and step-by-step
integration guides
[can be found here](https://mflt.io/embedded-getting-started).

## Getting Started

To start integrating in your platform today,
[create a Memfault cloud account](https://mflt.io/signup).

## Components

The SDK is designed as a collection of components, so you can include only what
is needed for your project. The SDK has been designed to have minimal impact on
code-space, bandwidth, and power consumption.

The [`components`](components/) directory folder contains the various components
of the SDK. Each component contains a `README.md`, source code, header files and
"platform" header files.

The platform header files describe the interfaces which the component relies on
that you must implement.

For some of the platform dependencies we have provided ports that can be linked
into your system directly, or used as a template for further customization. You
can find them in the [`ports`](ports/) folder.

For some of the popular MCUs & vendor SDKs, we have already provided a reference
implementation for platform dependencies which can be found in the
[`examples`](examples/) folder. These can also serve as a good example when
initially setting up the SDK on your platform.

### Main components

- `panics` – fault handling, coredump and reboot tracking and reboot loop
  detection API.
- `metrics` - used to monitor device health over time (i.e. connectivity,
  battery life, MCU resource utilization, hardware degradation, etc.)

Please refer to the `README.md` in each of these for more details.

### Support components

- `core` – common code that is used by all other components.
- `demo` - common code that is used by demo apps for the various platforms.
- `http` – http client API, to post coredumps and events directly to the
  Memfault service from devices.
- `util` – various utilities.

## Integrating the Memfault SDK

## Add Memfault SDK to Your Repository

The Memfault SDK can be added directly into your repository. The structure
typically looks like:

```bash
<YOUR_PROJECT>
├── third_party/memfault
│               ├── memfault-firmware-sdk (submodule)
│               │
│               │ # Files where port to your platform will be implemented
│               ├── memfault_platform_port.c
│               ├── memfault_platform_coredump_regions.c
│               │
│               │ # Configuration headers
│               ├── memfault_platform_config.h
│               ├── memfault_trace_reason_user_config.def
│               ├── memfault_metrics_heartbeat_config.def
│               └── memfault_platform_log_config.h
```

If you are using `git`, the Memfault SDK is typically added to a project as a
submodule:

```bash
git submodule add https://github.com/memfault/memfault-firmware-sdk.git $YOUR_PROJECT/third_party/memfault/memfault-firmware-sdk
```

This makes it easy to track the history of the Memfault SDK. You should not need
to make modifications to the Memfault SDK. The typical update flow is:

- `git pull` the latest upstream
- check [CHANGELOG.md](CHANGELOG.md) to see if any modifications are needed
- update to the new submodule commit in your repo.

Alternatively, the Memfault SDK may be added to a project as a git subtree or by
copying the source into a project.

## Add sources to Build System

### Make

If you are using `make`, `makefiles/MemfaultWorker.mk` can be used to very
easily collect the source files and include paths required by the SDK.

```c
MEMFAULT_SDK_ROOT := <The to the root of this repo from your project>
MEMFAULT_COMPONENTS := <The SDK components to be used, i.e "core util">
include $(MEMFAULT_SDK_ROOT)/makefiles/MemfaultWorker.mk
<YOUR_SRC_FILES> += $(MEMFAULT_COMPONENTS_SRCS)
<YOUR_INCLUDE_PATHS> += $(MEMFAULT_COMPONENTS_INC_FOLDERS)
```

### Cmake

If you are using `cmake`, `cmake/Memfault.cmake` in a similar fashion to
collection source files and include paths:

```c
set(MEMFAULT_SDK_ROOT <The path to the root of the memfault-firmware-sdk repo>)
list(APPEND MEMFAULT_COMPONENTS <The SDK components to be used, i.e "core util">)
include(${MEMFAULT_SDK_ROOT}/cmake/Memfault.cmake)
memfault_library(${MEMFAULT_SDK_ROOT} MEMFAULT_COMPONENTS
 MEMFAULT_COMPONENTS_SRCS MEMFAULT_COMPONENTS_INC_FOLDERS)

# ${MEMFAULT_COMPONENTS_SRCS} contains the sources
# needed for the library and ${MEMFAULT_COMPONENTS_INC_FOLDERS} contains the include paths
```

### Other Build Systems

If you are not using one of the above build systems, to include the SDK you need
to do is:

- Add the `.c` files located at `components/<component>/src/*.c` to your build
  system
- Add `components/<component>/include` to the include paths you pass to the
  compiler

#### Running the unit tests

The SDK code is covered extensively by unit tests. They can be found in the
`tests/` folder. If you'd like to run them yourself, check out the instructions
in [tests/README.md](tests/README.md).

To learn more about unit testing best practices for firmware development, check
out
[our blog post on this topic](https://interrupt.memfault.com/blog/unit-testing-basics)!

The unit tests are run by CircleCI upon every commit to this repo. See badges at
the top for build & test coverage status of the `master` branch.

## FAQ

- Why does a coredump not show up under "Issues" after uploading it?

  - Make sure to upload the symbols to the same project to which you upload
    coredumps. Also make sure the software type and software version reported by
    the device (see "Device information" in `components/core/README.md`) match
    the software type and software version that was entered when creating the
    Software Version and symbol artifact online.
    [More information on Build Ids and uploading Symbol Files can be found here](https://mflt.io/symbol-file-build-ids).

- I'm getting error XYZ, what to do now?

  - Don't hesitate to contact us for help! You can reach us through
    <https://mflt.io/contact-support>.

## License

Unless specifically indicated otherwise in a file, all memfault-firmware-sdk
files are all licensed under the [Memfault License](/LICENSE). (A few files in
the [examples](/examples) and [ports](/ports) directory are licensed differently
based on vendor requirements.)

Links

Supports all targets

License: Custom

To add this component to your project, run:

idf.py add-dependency "memfault/memfault-firmware-sdk^1.16.0"

or download archive

Stats

  • Archive size
    Archive size ~ 686.76 KB
  • Downloaded in total
    Downloaded in total 87 times
  • Downloaded this version
    This version: 24 times

Badge

memfault/memfault-firmware-sdk version: 1.16.0
|