Portable C++20 driver for the AS5047U magnetic encoder from ams with SPI interface, CRC protection, DAEC, and DFS™

📚 Table of Contents

Overview
Features
Quick Start
Installation
API Reference
Examples
Documentation
Contributing
License

📦 Overview

‍📖 📚🌐 Live Complete Documentation - Interactive guides, examples, and step-by-step tutorials

HF-AS5047U is a portable C++20 driver for the AS5047U magnetic encoder from ams. It delivers fast 14‑bit absolute angle readings over SPI, optional CRC protection and advanced features like Dynamic Angle Error Compensation (DAEC) and an adaptive Dynamic Filter System (DFS™). The sensor can also output incremental (A/B/I) and 3‑phase commutation (UVW) signals or a PWM encoded angle, making it a drop‑in replacement for optical encoders in high-performance motor control and robotics.

The driver uses a CRTP-based SpiInterface for hardware abstraction, allowing it to run on any platform (ESP32, STM32, Arduino, etc.) with zero runtime overhead. It implements all major features from the AS5047U datasheet including absolute angle readout with/without DAEC, velocity measurement, AGC and magnetic field diagnostics, ABI/UVW/PWM interface configuration, error/status flag handling, and full OTP programming sequence.

✨ Features

✅ 14-bit absolute angle with optional CRC check
✅ DAEC (Dynamic Angle Error Compensation) for low-latency angle correction
✅ DFS™ (Dynamic Filter System) adaptive noise filtering
✅ Stray-field immunity for robust operation
✅ Incremental ABI outputs up to 4096 PPR
✅ UVW commutation with programmable pole pairs
✅ PWM output option
✅ Diagnostics for AGC, magnitude and error flags
✅ OTP memory for permanent configuration
✅ Hardware Agnostic: SPI interface for platform independence
✅ Modern C++: C++20 with CRTP-based design
✅ Zero Overhead: CRTP-based design for compile-time polymorphism

🚀 Quick Start

#include "as5047u.hpp"
 
// 1. Implement the SPI interface (see platform_integration.md)
class MySpi : public as5047u::SpiInterface<MySpi> {
public:
    void transfer(const uint8_t* tx, uint8_t* rx, size_t len) {
        // Your SPI transfer implementation
    }
};
 
// 2. Create driver instance
MySpi spi;
as5047u::AS5047U encoder(spi, FrameFormat::SPI_24); // 24-bit frames with CRC
 
// 3. Read angle / velocity (unit-selected API)
float angle_deg = encoder.GetAngle(as5047u::AngleUnit::Degrees);      // 0..360
float angle_rad = encoder.GetAngle(as5047u::AngleUnit::Radians);      // 0..2π
float vel_rpm = encoder.GetVelocity(as5047u::VelocityUnit::Rpm);
float vel_dps = encoder.GetVelocity(as5047u::VelocityUnit::DegPerSec);
 
// 4. Diagnostics
uint8_t agc = encoder.GetAGC();            // automatic gain control
uint16_t mag = encoder.GetMagnitude();     // magnetic magnitude
uint16_t errors = encoder.GetErrorFlags(); // current error flags

For detailed setup, see Installation and Quick Start Guide.

🔧 Installation

Clone or copy the driver files into your project
Implement the SPI interface for your platform (see Platform Integration)
Include the header in your code:
#include "as5047u.hpp"
Compile with a C++20 or newer compiler

For detailed installation instructions, see docs/installation.md.

📖 API Reference

Method	Description
`GetAngle(AngleUnit)`	Read absolute angle in selected unit (LSB/deg/rad)
`GetVelocity(VelocityUnit)`	Read velocity in selected unit (LSB/deg/s/rad/s/RPM)
`GetAngle()`	Read 14-bit compensated absolute angle
`GetRawAngle()`	Read 14-bit raw absolute angle
`GetVelocity()`	Read signed 14-bit velocity (LSB units)
`GetVelocityDegPerSec()`	Velocity in degrees/sec
`GetVelocityRPM()`	Velocity in revolutions per minute
`GetAGC()`	Read AGC (0–255) value
`GetMagnitude()`	Read magnetic field magnitude
`GetErrorFlags()`	Read and clear error/status flags
`SetZeroPosition()`	Set new zero offset
`SetDirection()`	Set rotation direction (CW or CCW)
`SetABIResolution()`	Set ABI output resolution (10–14 bits)
`SetUVWPolePairs()`	Set UVW pole pairs (1–7)
`ConfigureInterface()`	Enable/disable ABI, UVW, PWM
`SetDynamicAngleCompensation()`	Enable/disable DAEC
`SetAdaptiveFilter()`	Enable/disable adaptive filter (DFS)
`SetFilterPreset()`	Set filter from preset (LowNoise, Balanced, HighBandwidth)
`GetAdaptiveFilterEnabled()`	Read whether adaptive filter is enabled
`GetFilterParameters()`	Read current K_min and K_max register codes
`ProgramOTP()`	Program current settings into OTP

For complete API documentation, see docs/api_reference.md.

Compatibility note: the unit-specific helpers (GetAngleDegrees(), GetVelocityRPM(), etc.) remain available for existing code, but new code should prefer the unit-enum overloads.

📊 Examples

For ESP32 examples and integration tests, see the examples/esp32 directory.

Detailed example walkthroughs are available in docs/examples.md.

📚 Documentation

For complete documentation, see the docs directory.

🤝 Contributing

Pull requests and suggestions are welcome! Please follow the existing code style and include tests for new features.

📄 License

This project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.