Módulo Bússola 3 Eixos GY-271 HMC5883L: Manual Técnico Completo

Introdução

Neste manual, será apresentado como instalar, configurar e utilizar o Módulo Bússola 3 Eixos GY-271 HMC5883L. Se desejar adquirir este produto, clique aqui.

O Módulo Bússola 3 Eixos GY-271 HMC5883L (código SKU RB0670) é uma unidade magnetométrica digital triaxial de alta sensibilidade projetada em placa ultracompacta ($18{,}0 \times 13{,}5\,\text{mm}$) em torno do circuito integrado HMC5883L da Honeywell (identificado pela marcação laser superior L883). Baseado em elementos sensores AMR (Anisotropic Magnetoresistive — magnetorresistência anisotrópica) acoplados a um conversor analógico-digital (ADC) interno de $12\,\text{bits}$, o módulo mede a densidade de fluxo magnético vetorial nos eixos ortogonais $X$, $Y$ e $Z$ em faixas dinâmicas programáveis de $\pm 0{,}88\,\text{Gauss}$ a $\pm 8{,}1\,\text{Gauss}$, transmitindo os dados via barramento I²C (Inter-Integrated Circuit) de até $400\,\text{kHz}$. Este guia técnico destina-se a estudantes, técnicos e engenheiros de sistemas embarcados e robótica móvel, reunindo especificações elétricas de folha de dados, mapeamento de pinos e registradores internos, equacionamento de calibração magnética (Hard-Iron e Soft-Iron), correção de declinação geográfica e firmwares completos para Arduino e ESP32.

Especificações técnicas

Principais especificações

Os parâmetros construtivos, magnéticos e de comunicação digital do Módulo Bússola 3 Eixos GY-271 HMC5883L estão consolidados na tabela a seguir:

Parâmetro	Especificação
Modelo Comercial	Módulo Bússola Digital / Magnetômetro Triaxial GY-271 HMC5883L
Código de Referência (SKU)	RB0670
Circuito Integrado Principal	Honeywell HMC5883L (Encapsulamento SMD LCC-16 sem chumbo de $3{,}0 \times 3{,}0 \times 0{,}9\,\text{mm}$, serigrafia L883)
Princípio Físico de Detecção	Pontes magnetorresistivas anisotrópicas (AMR de filme fino Permalloy $\text{NiFe}$) nos 3 eixos ($X$, $Y$, $Z$)
Resolução do Conversor Interno	ADC de $12\,\text{bits}$ integrado ao ASIC (saída em complemento de dois de $16\,\text{bits}$: -2048 a +2047)
Faixa Dinâmica de Campo Magnético	Selecionável por software entre $\pm 0{,}88\,\text{G}$ e $\pm 8{,}1\,\text{G}$ ($8$ escalas de ganho; padrão de fábrica: $\pm 1{,}3\,\text{Gauss}$)
Sensibilidade / Resolução Magnética	Até $0{,}73\,\text{mG/LSb}$ ($1370\,\text{LSb/Gauss}$ em $\pm 0{,}88\,\text{G}$); resolução linear prática de $2\,\text{mG}$ ($0{,}2\,\mu\text{T}$)
Precisão Típica de Azimute (Heading)	$1^\circ$ a $2^\circ$ de erro angular (após calibração Hard/Soft-Iron em plano nivelado)
Interface de Comunicação	I²C (Two-Wire Serial Interface) — Standard Mode ($100\,\text{kHz}$) e Fast Mode ($400\,\text{kHz}$)
Endereço I²C Fixo de Fábrica	0x1E ($7\,\text{bits}$) — Endereço de escrita: 0x3C / Endereço de leitura: 0x3D
Registradores de Identificação (IRA–IRC)	0x0A = 0x48 ('H'), 0x0B = 0x34 ('4'), 0x0C = 0x33 ('3')
Taxa de Atualização Contínua (ODR)	Programável em $0{,}75\,\text{Hz}$, $1{,}5\,\text{Hz}$, $3\,\text{Hz}$, $7{,}5\,\text{Hz}$, $15\,\text{Hz}$ (padrão), $30\,\text{Hz}$ e $75\,\text{Hz}$
Taxa Máxima em Medição Única	Até $160\,\text{Hz}$ em modo Single-Measurement monitorado via pino de interrupção DRDY
Condicionamento Elétrico na PCB	Regulador linear LDO de $+3{,}3\,\text{V}$ integrado + translação bidirecional de nível lógico I²C ($3{,}3\,\text{V} \leftrightarrow 5{,}0\,\text{V}$)
Conector de Interface	Barra de $5$ pinos machos com passo padrão de $2{,}54\,\text{mm}$ (VCC, GND, SCL, SDA, DRDY)
Dimensões Mecânicas ($C \times L$)	$18{,}0 \times 13{,}5\,\text{mm}$ (nominal $18 \times 13\,\text{mm}$), com $2$ furos de fixação $\varnothing\,3{,}0\,\text{mm}$

⚠️ Atenção: Em catálogos comerciais traduzidos automaticamente, é comum encontrar duas imprecisões terminológicas sobre o GY-271: a indicação de faixa “±1,3 – 8 Graus” refere-se na realidade à unidade física magnética Gauss ($\pm 1{,}3\,\text{G}$ a $\pm 8{,}1\,\text{G}$), onde $1\,\text{Gauss} = 100\,\mu\text{T}$ ($0{,}1\,\text{mT}$); além disso, o módulo GY-271 é exclusivamente um magnetômetro triaxial (bússola eletrônica) e não incorpora acelerômetro MEMS em seu encapsulamento.

Características elétricas e operacionais

Os limites elétricos absolutos e os parâmetros operacionais do circuito integrado HMC5883L combinados ao circuito regulador da placa GY-271 estão detalhados abaixo:

Parâmetro Elétrico / Operacional	Mínimo	Típico	Máximo	Unidade	Condição / Observação Técnica
Tensão de Alimentação na Placa (VCC)	$3{,}00$	$3{,}30\text{ / }5{,}00$	$5{,}50$	$\text{VDC}$	Entrada do regulador LDO onboard SOT-23 (662K / XC6206 de $3{,}3\,\text{V}$)
Tensão Analógica Interna do CI ($V_{\text{DD}}$)	$2{,}16$	$3{,}30$	$3{,}60$	$\text{VDC}$	Fornecida internamente pelo regulador LDO da placa (limite absoluto sem dano: $4{,}8\,\text{V}$)
Tensão de Interface Digital do CI ($V_{\text{DDIO}}$)	$1{,}71$	$3{,}30$	$3{,}60$	$\text{VDC}$	Malha interna de $3{,}3\,\text{V}$ acoplada ao estágio translador de nível da PCB
Nível Lógico Alto no Barramento I²C (SCL/SDA)	$0{,}7 \cdot V_{\text{CC}}$	$3{,}30\text{ / }5{,}00$	$5{,}25$	$\text{V}$	Suporta mestres de $3{,}3\,\text{V}$ (ESP32) e $5{,}0\,\text{V}$ (Arduino AVR) via pull-ups 222 ($2{,}2\,\text{k}\Omega$)
Tensão de Saída no Pino DRDY	$0{,}00$	—	$3{,}30$	$\text{V}$	Saída digital direta do pino 15 do HMC5883L referenciada a $V_{\text{DDIO}} = 3{,}3\,\text{V}$
Corrente Média do Núcleo HMC5883L (Ativo)	—	$100$	$150$	$\mu\text{A}$	Taxa de $7{,}5\,\text{Hz}$ a $15\,\text{Hz}$ ($V_{\text{DD}} = 3{,}3\,\text{V}$); consumo em modo Idle: $2\,\mu\text{A}$
Corrente Total do Módulo GY-271	$0{,}15$	$0{,}35$	$2{,}50$	$\text{mA}$	Inclui corrente quiescente do regulador LDO e pulsos de desmagnetização Set/Reset
Linearidade Magnética (% Fundo de Escala)	—	$\pm 0{,}1$	—	$\%\,\text{FS}$	Na escala de $\pm 2{,}0\,\text{Gauss}$ com histerese típica de $\pm 25\,\text{ppm}$
** Sensibilidade Transversal (Cross-Axis)**	—	$\pm 0{,}2$	—	$\%\,\text{FS/G}$	Rejeição de acoplamento cruzado entre os eixos ortogonais $X$, $Y$ e $Z$
Exposição Magnética Máxima sem Dano	—	—	$10.000$	$\text{Gauss}$	$1\,\text{Tesla}$ — recuperado automaticamente pela bobina interna Set/Reset Strap
Frequência de Clock I²C ($f_{\text{SCL}}$)	$0$	$100$	$400$	$\text{kHz}$	Suporta operação Standard e Fast Mode sem exigência de clock stretching
Temperatura Operacional ($T_A$)	$-30$	$+25$	$+85$	$\text{°C}$	Faixa de armazenamento não energizado: $-40\,\text{°C}$ a $+125\,\text{°C}$

Descrição do produto

O que é o Módulo Bússola 3 Eixos GY-271 HMC5883L?

O Módulo Bússola 3 Eixos GY-271 HMC5883L é uma placa breakout de instrumentação magnética construída sobre o sensor monolítico HMC5883L da Honeywell. Diferentemente de sensores baseados em efeito Hall convencionais — cujo elevado ruído térmico limita a detecção de campos fracos como o campo geomagnético terrestre (que varia de apenas $0{,}22\,\text{Gauss}$ na Anomalia Magnética do Atlântico Sul sobre o Brasil até $0{,}65\,\text{Gauss}$ próximo aos polos) —, o HMC5883L emprega pontes de Wheatstone magnetorresistivas anisotrópicas (AMR). Essas pontes são fabricadas por deposição de filmes finos de liga ferromagnética Permalloy ($\text{NiFe}$) cuja resistência elétrica varia de forma altamente linear em função do ângulo entre a corrente elétrica de polarização e o vetor de indução magnética externo $\vec{B} = [B_x, B_y, B_z]^T$.

No interior do encapsulamento LCC-16 (L883), o chip integra amplificadores de instrumentação de baixo ruído, um conversor ADC de $12\,\text{bits}$, lógica de controle I²C, bobinas internas de calibração de ganho (Self-Test Bias Strap) e drivers automáticos de pulso Set/Reset alimentados pelo capacitor cerâmico externo de reserva (C1 de $4{,}7\,\mu\text{F}$). A cada ciclo de medição, o circuito Set/Reset dispara um pulso curto de alta corrente que realinha os domínios magnéticos das fitas de Permalloy em polaridades opostas, eliminando a deriva térmica de offset da ponte e restaurando instantaneamente o sensor mesmo após a aproximação acidental de um ímã permanente forte. Na placa GY-271, um regulador linear LDO de $3{,}3\,\text{V}$ e um par de transistores MOSFET SMD com resistores pull-up de $2{,}2\,\text{k}\Omega$ (222) adaptam tanto a alimentação quanto os sinais SDA e SCL para microcontroladores de $3{,}3\,\text{V}$ e $5{,}0\,\text{V}$.

Para que serve?

• Navegação autônoma e controle de rumo (Heading / Yaw) em robótica móvel, VANTs/drones e embarcações USV: Determinação contínua do azimute magnético em relação ao Norte para malhas fechadas de direção (PID de orientação) e correção de deriva acumulada de giroscópios MEMS em sistemas AHRS (Attitude and Heading Reference System).
• Posicionamento azimutal de rastreadores solares (Solar Trackers) e rotores de antenas direcionais: Alinhamento angular automático de painéis fotovoltaicos de dois eixos, telescópios amadores e antenas de telemetria/satélite em instalações fixas ou móveis sem necessidade de chaves fim de curso mecânicas de referência norte.
• Detecção não invasiva de presença veicular e anomalias ferromagnéticas: Sensoriamento de perturbações locais no campo geomagnético causadas pela massa metálica de automóveis em vagas de estacionamento inteligentes, cancelas automatizadas, contagem de tráfego e chaves magnéticas industriais sem contato.

Por que devo usar?

• Sensibilidade superior da tecnologia AMR frente a sensores Hall: Com resolução prática de $2\,\text{mG}$ ($0{,}2\,\mu\text{T}$) e ruído dezenas de vezes inferior ao de magnetômetros Hall econômicos, o HMC5883L resolve variações angulares de $1^\circ$ a $2^\circ$ mesmo no território brasileiro, onde a intensidade horizontal do campo magnético terrestre é uma das menores do planeta ($\approx 0{,}18\,\text{G}$ a $0{,}25\,\text{G}$).
• Desmagnetização automática (Set/Reset) e autoteste integrados em silício: O circuito interno elimina magnetização residual (perming) caso o módulo passe perto de motores ou ímãs e disponibiliza uma fonte interna de excitação magnética conhecida ($\pm 1{,}16\,\text{G}$ em $X/Y$ e $\pm 1{,}08\,\text{G}$ em $Z$) para auditar a integridade dos 3 eixos via software em campo.
• Compatibilidade elétrica imediata com barramentos de $3{,}3\,\text{V}$ e $5{,}0\,\text{V}$: O estágio regulador LDO e o translador bidirecional de nível lógico montados na própria placa GY-271 permitem conexão direta tanto ao Arduino Uno/Mega ($5\,\text{V}$) quanto ao ESP32, STM32 e Raspberry Pi ($3{,}3\,\text{V}$) usando apenas 4 fios essenciais.

Quando devo usar?

Este módulo é a escolha recomendada quando o projeto demanda orientação absoluta em relação ao Norte magnético/geográfico (eliminação do drift de guinada/Yaw que todo giroscópio sofre ao integrar velocidade angular no tempo), medição vetorial de campos magnéticos fracos ($\le \pm 8{,}1\,\text{Gauss}$) com baixíssimo consumo energético ($\approx 100\,\mu\text{A}$ no CI) ou sensoriamento de objetos ferromagnéticos a curta distância via barramento I²C compartilhado.

Por outro lado, o GY-271 isolado não deve ser empregado sem componentes complementares ou alternativas nos seguintes casos:

• Plataformas sujeitas a inclinações contínuas de rolagem (Roll) e arfagem (Pitch) sem acelerômetro auxiliar: Se o chassi do robô, drone ou veículo inclinar mais que $3^\circ\text{–}5^\circ$ fora do plano horizontal, a projeção da componente vertical do campo terrestre distorce severamente o cálculo simples atan2(Y, X). Nesses sistemas, combine o GY-271 no mesmo barramento I²C com o Acelerômetro e Giroscópio 3 Eixos MPU-6050 (formando uma IMU de 9 graus de liberdade com compensação matemática de inclinação) ou utilize um módulo integrado 9-DOF (como MPU-9250 ou BNO055).
• Medição direta na superfície de ímãs permanentes de neodímio ($\text{NdFeB}$) ou sensores de corrente de alta intensidade ($> 8{,}1\,\text{Gauss}$): Campos acima de $\pm 8{,}1\,\text{G}$ ($0{,}81\,\text{mT}$) saturam o ADC do HMC5883L (retornando o código de overflow -4096). Para medir campos intensos de dezenas ou centenas de Gauss (ex.: tacômetros magnéticos ou posição linear com ímã colado), utilize sensores Hall lineares analógicos (como SS49E / OH49E, faixa de $\pm 1000\,\text{G}$) ou chaves Hall digitais (A3144).
• Ambientes internos confinados dentro de gaiolas metálicas ou colados a motores de tração DC de alta corrente: Se a distorção magnética variável gerada por cabos de potência PWM superar a intensidade do campo terrestre sem possibilidade de afastar o sensor por uma haste/torre (mast), utilize odometria diferencial por encoders fundida a um giroscópio MEMS de baixa deriva para navegação relativa de curto prazo.

Pinout e diagrama de entradas/saídas

O Módulo GY-271 possui uma barra frontal de 5 terminais padrão $2{,}54\,\text{mm}$, além da serigrafia dos eixos ortogonais $X$, $Y$ e $Z$ impressa na face superior da PCB azul (que define o referencial geométrico de instalação no chassi do robô):

Pino (Serigrafia)	Nome Técnico	Direção (Relativa ao Módulo)	Nível Elétrico	Função Técnica Detalhada
VCC	Alimentação Positiva	Entrada	$+3{,}0\,\text{VDC}$ a $+5{,}0\,\text{VDC}$	Entrada do regulador linear LDO de $+3{,}3\,\text{V}$ da placa. Pode receber tanto $+5\,\text{V}$ (Arduino) quanto $+3{,}3\,\text{V}$ (ESP32).
GND	Referência de Terra	Referência	$0\,\text{V}$	Terra comum de alimentação e referência de sinal lógico I²C.
SCL	Serial Clock (I²C)	Entrada (Dreno Aberto)	$3{,}3\,\text{V}$ / $5{,}0\,\text{V}$	Linha de clock síncrono I²C até $400\,\text{kHz}$. Possui resistor pull-up e estágio translador de nível na placa.
SDA	Serial Data (I²C)	Bidirecional (Dreno Aberto)	$3{,}3\,\text{V}$ / $5{,}0\,\text{V}$	Linha serial de dados I²C. Possui resistor pull-up de $2{,}2\,\text{k}\Omega$ (222) e translador MOSFET bidirecional integrado.
DRDY	Data Ready Interrupt	Saída Digital CMOS	$0\,\text{V}$ / $+3{,}3\,\text{V}$	Pino opcional de interrupção de dados prontos (pino 15 do HMC5883L). Pulsa em nível LOW por $\approx 250\,\mu\text{s}$ e retorna a HIGH sempre que os 6 bytes de medição são atualizados.

No nível de protocolo interno no endereço I²C 0x1E, o controlador Honeywell HMC5883L (L883) organiza sua memória em 13 registradores de $8\,\text{bits}$ (0x00 a 0x0C). Observe com máxima atenção a ordem física não alfabética dos eixos nos registradores de dados (X, seguido de Z, e por último Y):

Endereço Hex	Nome Oficial do Registrador	Acesso	Valor Padrão	Estrutura de Bits e Função no Hardware
0x00	Configuration Register A (CRA)	Leitura / Escrita	0x10	[6:5] MA1:MA0 (Média: 00=1, 01=2, 10=4, 11=8 amostras); [4:2] DO2:DO0 (Taxa ODR: 100=$15\,\text{Hz}$); [1:0] MS1:MS0 (Modo de polarização/Autoteste).
0x01	Configuration Register B (CRB)	Leitura / Escrita	0x20	[7:5] GN2:GN0 (Escala de ganho magnético; 001 = $\pm 1{,}3\,\text{G}$ / $1090\,\text{LSb/G}$). Os bits [4:0] devem ser escritos sempre como 0.
0x02	Mode Register (MR)	Leitura / Escrita	0x01	[1:0] MD1:MD0 (00 = Medição Contínua; 01 = Medição Única/Single; 10 ou 11 = Repouso/Idle). Bit [7] HS habilita I²C High Speed.
0x03	Data Output X MSB (DXRA)	Somente Leitura	—	Byte mais significativo (MSB) da leitura de $16\,\text{bits}$ do Eixo X em complemento de 2.
0x04	Data Output X LSB (DXRB)	Somente Leitura	—	Byte menos significativo (LSB) da leitura de $16\,\text{bits}$ do Eixo X.
0x05	Data Output Z MSB (DZRA)	Somente Leitura	—	Atenção à ordem X–Z–Y: Byte mais significativo (MSB) da leitura de $16\,\text{bits}$ do Eixo Z (vertical).
0x06	Data Output Z LSB (DZRB)	Somente Leitura	—	Byte menos significativo (LSB) da leitura de $16\,\text{bits}$ do Eixo Z.
0x07	Data Output Y MSB (DYRA)	Somente Leitura	—	Byte mais significativo (MSB) da leitura de $16\,\text{bits}$ do Eixo Y.
0x08	Data Output Y LSB (DYRB)	Somente Leitura	—	Byte menos significativo (LSB) da leitura de $16\,\text{bits}$ do Eixo Y.
0x09	Status Register (SR)	Somente Leitura	0x00	Bit 1 (LOCK): trava de atualização durante leitura parcial; Bit 0 (RDY): indica nova amostra pronta nos 6 registradores.
0x0A–0x0C	Identification Registers A, B, C	Somente Leitura	'H', '4', '3'	Assinatura fixa em ROM do HMC5883L original: 0x48, 0x34, 0x33 (ASCII "H43").

💡 Dica: O HMC5883L possui uma trava de integridade atômica (LOCK): assim que o microcontrolador lê o primeiro registrador (0x03), o sensor bloqueia novas atualizações internas até que todos os 6 bytes (0x03 até 0x08) sejam lidos integralmente na mesma transação I²C. Se o seu código ler apenas 4 bytes tentando economizar o eixo $Z$, os registradores ficarão permanentemente congelados na primeira leitura!

Como fazer a ligação

Requisitos de instalação e alimentação

1. Alimentação DC limpa e compatibilidade lógica ($3{,}3\,\text{V}$ ou $5{,}0\,\text{V}$):
   • O pino VCC aceita diretamente tensões contínuas reguladas entre $3{,}0\,\text{VDC}$ e $5{,}0\,\text{VDC}$. Em placas Arduino Uno, Nano ou Mega 2560, conecte VCC ao pino 5V; em placas de $3{,}3\,\text{V}$ nativos como ESP32, ESP8266, RP2040 ou STM32, conecte VCC preferencialmente ao pino regulado 3V3 para manter todo o barramento I²C unificado em $3{,}3\,\text{V}$ sem queda mínima (dropout) no LDO.
   • Como a placa GY-271 já incorpora resistores pull-up SMD de $2{,}2\,\text{k}\Omega$ (222) nas linhas SDA e SCL, não são necessários resistores externos adicionais para cabos curtos de bancada ou chassi (até $30\,\text{cm}$).
2. Isolamento magnético e fixação mecânica não ferromagnética (Crítico):
   • Diferente de sensores ópticos ou térmicos, uma bússola digital mede campos da ordem de $0{,}2\,\text{Gauss}$ — qualquer parafuso de aço carbono/niquelado preso aos furos de $3\,\text{mm}$ da placa cria um dipolo magnético local maior que o próprio campo da Terra. Utilize exclusivamente espaçadores (standoffs) e parafusos M2.5/M3 de Nylon (poliamida), plástico ABS/PETG ou latão não magnético.
   • Posicione o módulo a uma distância mínima de $10\,\text{cm}$ a $15\,\text{cm}$ (idealmente elevado em pequena haste/torre como nos drones GPS) longe de motores DC com ímãs permanentes, servo motores, alto-falantes, relés eletromecânicos, baterias Li-Ion com invólucro de aço niquelado e trilhas de potência de alta corrente ($I > 1\,\text{A}$ gera campo magnético $B = \mu_0 I / 2\pi r$).
3. Alinhamento geométrico dos eixos na montagem:
   • A serigrafia na face da PCB indica a direção positiva dos eixos $+X$ e $+Y$. Monte a placa nivelada paralelamente ao solo com o eixo $+X$ apontado exatamente para a frente (proa) do robô ou veículo, garantindo correspondência direta entre o ângulo calculado e a direção de deslocamento.

Diagrama de ligação elétrica

A figura abaixo apresenta o diagrama de ligação elétrica em blocos do Módulo Bússola 3 Eixos GY-271 HMC5883L, detalhando as opções de alimentação DC ($3{,}0\,\text{V}$ a $5{,}0\,\text{V}$), a conexão direta I²C de alta velocidade ($400\,\text{kHz}$) com Arduino Uno R3 e ESP32 DevKit V1, o uso opcional do pino de interrupção DRDY e o compartilhamento do barramento I²C com uma IMU MPU-6050 para compensação de inclinação:

Conforme ilustrado no infográfico técnico, a arquitetura multiponto do barramento I²C permite que apenas duas linhas de comunicação (SCL e SDA) conectem o módulo GY-271 (endereço escravo fixo 0x1E) simultaneamente a sensores inerciais complementares como o acelerômetro/giroscópio MPU-6050 (endereço 0x68), sem conflito de endereçamento e economizando portas GPIO do microcontrolador.

Tabela de conexões dos terminais

O mapeamento completo ponto a ponto (De $\to$ Para) para integração com Arduino Uno / Nano (e equivalências no Mega 2560) está especificado na tabela abaixo:

Terminal de Origem (Arduino Uno / Nano)	Terminal de Destino (GY-271 HMC5883L)	Cor Sugerida do Fio	Tipo de Sinal	Observação Técnica
Pino 5V (Arduino)	Pino VCC	Vermelho	Alimentação DC ($+5{,}0\,\text{V}$)	Regulado internamente para $+3{,}3\,\text{V}$ pelo LDO da PCB
Pino GND (Arduino)	Pino GND	Preto	Terra Comum ($0\,\text{V}$)	Referência comum de alimentação e barramento I²C
Pino A5 / SCL (Arduino Uno)	Pino SCL	Amarelo ou Laranja	Clock Síncrono I²C ($400\,\text{kHz}$)	No Arduino Mega 2560, ligar no Pino D21 (SCL)
Pino A4 / SDA (Arduino Uno)	Pino SDA	Azul ou Verde	Dados Bidirecionais I²C	No Arduino Mega 2560, ligar no Pino D20 (SDA)
Pino D2 / INT0 (Opcional)	Pino DRDY	Branco ou Roxo	Saída de Interrupção ($3{,}3\,\text{V}$)	Opcional — necessário apenas para amostragem de $160\,\text{Hz}$ via IRQ

Para integração nativa em $3{,}3\,\text{V}$ com o ESP32 DevKit V1 (e expansão opcional 9-DOF com MPU-6050 no mesmo barramento), siga rigorosamente a tabela de pinagem a seguir:

Terminal no ESP32 DevKit V1	Terminal no GY-271 (0x1E)	Terminal no MPU-6050 Opcional (0x68)	Função Elétrica no Sistema
Pino 3V3	Pino VCC	Pino VCC	Alimentação regulada unificada em $+3{,}3\,\text{VDC}$
Pino GND	Pino GND	Pino GND	Terra comum ($0\,\text{V}$)
GPIO 22 (Wire SCL)	Pino SCL	Pino SCL	Linha de Clock I²C compartilhada ($400\,\text{kHz}$)
GPIO 21 (Wire SDA)	Pino SDA	Pino SDA	Linha de Dados I²C compartilhada
GPIO 4 (Entrada Digital)	Pino DRDY (Opcional)	Livre (INT em outro GPIO)	Disparo por interrupção externa de dados magnéticos prontos

Cuidados e observações de segurança

⛔ Perigo: Nunca inverta a polaridade entre os pinos VCC e GND nem aplique tensões provenientes de baterias automotivas ou LiPo ($7{,}4\,\text{V}$, $11{,}1\,\text{V}$ ou $12\,\text{V}$) diretamente ao pino VCC! A inversão de polaridade ou sobretensão acima de $5{,}5\,\text{VDC}$ destrói instantaneamente o regulador linear SOT-23 e pode colocar em curto o barramento interno $V_{\text{DD}}$ do HMC5883L (cujo limite máximo absoluto é $4{,}8\,\text{V}$), inutilizando permanentemente o sensor.

⚠️ Atenção: Cuidado ao soldar a barra de pinos próxima ao chip L883 e evite utilizar pontas de ferro de solda fortemente magnetizadas ou suportes magnéticos de bancada durante os testes! Realize a soldagem dos 5 pinos com estação regulada a $320\,\text{°C}\text{–}350\,\text{°C}$ em menos de $3\,\text{segundos}$ por ilha. Ao testar a bússola sobre a bancada, certifique-se de que não há chaves de fenda imantadas, celulares com anel magnético (MagSafe), alto-falantes de notebook ou estrutura de aço sob o tampo da mesa, pois esses elementos desviam o Norte medido em dezenas de graus.

💡 Dica: Verificação de autenticidade do CI (L883 vs. DA5883): O modelo RB0670 fornecido pela RoboBuilders utiliza o CI padrão HMC5883L (L883) no endereço I²C 0x1E. Caso você esteja fazendo manutenção em módulos GY-271 antigos de terceiros que não respondam em 0x1E, inspecione a gravação a laser sobre o chip com uma lupa: placas marcadas como DA5883 utilizam o clone chinês QST QMC5883L, que responde no endereço 0x0D e possui mapa de registradores incompatível. O firmware de diagnóstico fornecido neste manual detecta e informa automaticamente ambos os casos no Monitor Serial!

Como usar

Guia de operação passo a passo

1. Inspeção física e nivelamento na bancada: Fixe o módulo GY-271 em uma protoboard ou suporte plástico nivelado horizontalmente, afastado pelo menos $20\,\text{cm}$ de fontes chaveadas, notebooks e celulares. Observe as setas X e Y impressas na placa para identificar a referência frontal.
2. Conexão ao microcontrolador e energização: Realize as 4 ligações fundamentais (VCC, GND, SCL, SDA) conforme a tabela da seção anterior e conecte o cabo USB ao computador.
3. Consulta da Declinação Magnética Local ($\delta_{\text{mag}}$): O polo Norte Magnético não coincide geograficamente com o Polo Norte Verdadeiro (eixo de rotação da Terra). No Brasil, a declinação magnética é fortemente negativa (Oeste) — variando tipicamente entre $-18^\circ$ e $-23^\circ$ conforme o estado (por exemplo: São Paulo/MG $\approx -21{,}6^\circ$; Rio de Janeiro $\approx -22{,}5^\circ$; Curitiba $\approx -19{,}8^\circ$; Recife $\approx -21{,}7^\circ$; Manaus $\approx -15{,}2^\circ$). Consulte o valor exato da sua cidade na calculadora oficial IGRF do NOAA (Magnetic Field Calculator) e insira na constante DECLINACAO_MAG_GRAUS do código.
4. Gravação do firmware e execução da Calibração Hard/Soft-Iron ([C]): Carregue o Exemplo 1 abaixo, abra o Monitor Serial em $115200\,\text{bps}$ e envie a letra C. Durante a janela de $15\,\text{segundos}$, gire o módulo (ou o robô completo já montado com suas baterias e motores) lentamente em $360^\circ$ no plano horizontal para capturar os extremos $B_{\min}$ e $B_{\max}$ reais da estrutura.
5. Validação com Autoteste Interno ([T]) e Leitura Contínua: Envie a letra T pelo Monitor Serial caso deseje acionar a bobina interna de Self-Test da Honeywell para comprovar a calibração de fábrica dos 3 canais AMR, retornando automaticamente à leitura contínua de azimute verdadeiro ($0^\circ$ a $360^\circ$) e pontos cardeais.

Modos de operação e ajustes

Escalas de ganho programável (Registrador CRB — 0x01)

Os 3 bits mais significativos (GN2:GN0, posições CRB7:CRB5) do Configuration Register B (0x01) ajustam o ganho do amplificador interno do HMC5883L em 8 faixas simétricas. Para bússola terrestre, a escala padrão 0x20 ($\pm 1{,}3\,\text{Gauss}$) oferece a melhor relação sinal-ruído sem risco de saturação; caso algum eixo atinja o valor sentinela de overflow -4096 (0xF000) devido a campos parasitas próximos, reduza o ganho conforme a tabela:

Código GN2:GN0	Valor Hex em 0x01	Faixa Recomendada ($\text{Gauss}$)	Faixa Equivalente ($\mu\text{T}$)	Ganho Digital ($\text{LSb/Gauss}$)	Resolução Escalar ($\text{mG/LSb}$)
000	0x00	$\pm 0{,}88\,\text{G}$	$\pm 88\,\mu\text{T}$	$1370$	$0{,}73$
001 (Padrão)	0x20	$\pm 1{,}30\,\text{G}$	$\pm 130\,\mu\text{T}$	$1090$	$0{,}92$
010	0x40	$\pm 1{,}90\,\text{G}$	$\pm 190\,\mu\text{T}$	$820$	$1{,}22$
011	0x60	$\pm 2{,}50\,\text{G}$	$\pm 250\,\mu\text{T}$	$660$	$1{,}52$
100	0x80	$\pm 4{,}00\,\text{G}$	$\pm 400\,\mu\text{T}$	$440$	$2{,}27$
101	0xA0	$\pm 4{,}70\,\text{G}$	$\pm 470\,\mu\text{T}$	$390$	$2{,}56$
110	0xC0	$\pm 5{,}60\,\text{G}$	$\pm 560\,\mu\text{T}$	$330$	$3{,}03$
111	0xE0	$\pm 8{,}10\,\text{G}$	$\pm 810\,\mu\text{T}$	$230$	$4{,}35$

Modos de amostragem, média em hardware (CRA — 0x00) e estados de energia (MR — 0x02)

No registrador CRA (0x00), recomenda-se configurar o valor 0x70 (0b01110000), que habilita a média interna em hardware de $8$ amostras (MA = 11) antes de cada atualização de saída a $15\,\text{Hz}$ (DO = 100) — reduzindo o ruído branco de medição em um fator de $\sqrt{8} \approx 2{,}83\times$ sem custo computacional para o microcontrolador. Já o Mode Register (0x02) define o regime energético:

• Modo Contínuo (0x00): Realiza conversões periódicas automáticas na frequência definida em DO2:DO0 ($0{,}75\,\text{Hz}$ até $75\,\text{Hz}$). Ideal para robôs móveis, drones e telemetria em tempo real.
• Modo de Medição Única / Single-Measurement (0x01 — padrão ao ligar): Executa uma única conversão nos 3 eixos, atualiza os registradores de dados, aciona o pino DRDY e retorna imediatamente ao estado Idle ($2\,\mu\text{A}$). Permite tanto ultra-baixo consumo em dataloggers a bateria quanto amostragem máxima de até $160\,\text{Hz}$ quando rearmado imediatamente após cada pulso de DRDY.
• Modo Idle (0x02 / 0x03): Desliga o ADC e os amplificadores internos, mantendo apenas a interface I²C ativa com corrente típica de $2\,\mu\text{A}$.

Equacionamento matemático: conversão física, calibração Hard/Soft-Iron, declinação e compensação 3D

A leitura bruta de cada eixo ($\text{ADC}_x, \text{ADC}_y, \text{ADC}_z \in [-2048, +2047]$) é convertida para densidade de fluxo magnético em Gauss ($\text{G}$) e microteslas ($\mu\text{T}$) dividindo-se pelo ganho digital $G_{\text{LSb}}$ correspondente à escala configurada (por exemplo, $G_{\text{LSb}} = 1090\,\text{LSb/G}$):

$$B_{\text{eixo}}\,[\text{G}] = \frac{\text{ADC}_{\text{eixo}}}{G_{\text{LSb}}} \qquad \text{e} \qquad B_{\text{eixo}}\,[\mu\text{T}] = B_{\text{eixo}}\,[\text{G}] \times 100$$

Ao girar uma bússola ideal em $360^\circ$ no plano horizontal, os pontos $(B_x, B_y)$ deveriam descrever uma circunferência perfeita centrada na origem $(0, 0)$. Na prática robótica, campos magnéticos permanentes do chassi (distorção Hard-Iron) deslocam o centro da circunferência por um vetor de offset $(b_x, b_y)$, enquanto materiais ferromagnéticos não magnetizados próximos (distorção Soft-Iron) deformam a circunferência em uma elipse de semieixos $(s_x, s_y)$. Coletando os valores mínimos e máximos ao girar o robô em $360^\circ$, calculam-se os parâmetros de calibração:

$$b_x = \frac{B_{x,\max} + B_{x,\min}}{2}, \qquad b_y = \frac{B_{y,\max} + B_{y,\min}}{2}$$ $$s_x = \frac{B_{x,\max} - B_{x,\min}}{2}, \qquad s_y = \frac{B_{y,\max} - B_{y,\min}}{2}, \qquad s_{\text{méd}} = \frac{s_x + s_y}{2}$$

Aplicando a subtração de offset (Hard-Iron) seguida do reescalonamento radial (Soft-Iron diagonal), restauram-se as componentes horizontais calibradas:

$$B_{x,\text{cal}} = \left(B_x - b_x\right) \cdot \frac{s_{\text{méd}}}{s_x}, \qquad B_{y,\text{cal}} = \left(B_y - b_y\right) \cdot \frac{s_{\text{méd}}}{s_y}$$

Com o módulo nivelado no plano horizontal, o azimute magnético ($\psi_{\text{mag}}$ em radianos) e o Azimute Geográfico Verdadeiro ($\psi_{\text{verdadeiro}}$ em graus de $0^\circ$ a $360^\circ$) somado à declinação magnética local ($\delta_{\text{mag}}$) são obtidos pela função arco-tangente de quatro quadrantes:

$$\psi_{\text{mag}} = \operatorname{atan2}\!\left(B_{y,\text{cal}},\, B_{x,\text{cal}}\right)$$ $$\psi_{\text{verdadeiro}}\,[^\circ] = \left(\psi_{\text{mag}} \cdot \frac{180^\circ}{\pi} + \delta_{\text{mag}} + 360^\circ\right) \bmod 360^\circ$$

Caso o sistema embarcado opere sobre terrenos irregulares ou em veículos aéreos/aquáticos com ângulos conhecidos de rolagem (Roll $\phi$) e arfagem (Pitch $\theta$) medidos por um acelerômetro triaxial (como o MPU-6050), projeta-se o vetor magnético tridimensional $[B_{x,\text{cal}}, B_{y,\text{cal}}, B_{z,\text{cal}}]^T$ de volta ao plano horizontal terrestre antes de aplicar $\operatorname{atan2}(B_{y,h}, B_{x,h})$:

$$B_{x,h} = B_{x,\text{cal}} \cos\theta + B_{y,\text{cal}} \sin\phi \sin\theta + B_{z,\text{cal}} \cos\phi \sin\theta$$ $$B_{y,h} = B_{y,\text{cal}} \cos\phi - B_{z,\text{cal}} \sin\phi$$

Exemplos práticos de uso

Exemplo 1: Console Completo de Bancada — Driver I²C Nativo, Autoteste Interno e Calibração Hard/Soft-Iron (Arduino e ESP32)

Este primeiro firmware comunica-se diretamente com os registradores do HMC5883L (0x1E) usando apenas a biblioteca nativa <Wire.h> (dispensando bibliotecas externas), operando o barramento I²C em $400\,\text{kHz}$. Ele verifica a assinatura oficial "H43" nos registradores 0x0A–0x0C (alertando caso detecte clones em outros endereços), trata a ordem correta dos registradores X, Z, Y, detecta saturação magnética (-4096), executa a rotina interativa de calibração Hard/Soft-Iron de $15\,\text{s}$ pelo comando serial [C] e valida as bobinas internas de Self-Test da Honeywell pelo comando [T]:

/**
 * ============================================================================
 * Projeto: Bussola Digital de Precisao, Calibracao Hard/Soft-Iron e Self-Test
 * Produto: Modulo Bussola 3 Eixos GY-271 HMC5883L (SKU: RB0670 - CI L883)
 * Interface: I2C Fast Mode (400 kHz) - Endereco Nativo 0x1E (Sem libs externas)
 * Plataformas: Arduino (Uno/Nano/Mega) e ESP32 (Selecao automatica de pinos)
 * ============================================================================
 */

#include <Arduino.h>
#include <Wire.h>
#include <math.h>

// Endereco I2C de 7 bits e mapa de registradores oficiais do Honeywell HMC5883L
const uint8_t HMC5883L_ADDR     = 0x1E;
const uint8_t QMC5883L_ALT_ADDR = 0x0D; // Apenas para alerta de diagnostico em bancada

const uint8_t REG_CRA    = 0x00; // Configuration Register A
const uint8_t REG_CRB    = 0x01; // Configuration Register B (Ganho)
const uint8_t REG_MODE   = 0x02; // Mode Register
const uint8_t REG_DATA_X = 0x03; // Inicio dos 6 bytes: X_MSB, X_LSB, Z_MSB, Z_LSB, Y_MSB, Y_LSB
const uint8_t REG_STATUS = 0x09; // Status Register (LOCK / RDY)
const uint8_t REG_IDA    = 0x0A; // Identification Registers A, B, C ('H', '4', '3')

// Configuracao padrao: +-1.3 Gauss (CRB = 0x20 -> Ganho = 1090.0 LSb/Gauss)
const uint8_t GANHO_CRB_HEX   = 0x20;
const float   GANHO_LSB_GAUSS = 1090.0f;

// Declinacao Magnetica Local em graus (Negativa para Oeste no Brasil)
// Exemplos: Sudeste (SP/MG/RJ) ~ -21.6 a -22.5 | Sul ~ -19.8 | Nordeste ~ -21.7
const float DECLINACAO_MAG_GRAUS = -21.6f;

// Parametros ativos de calibracao Hard-Iron (offsets em Gauss) e Soft-Iron (escalas)
float offsetBx = 0.0f, offsetBy = 0.0f, offsetBz = 0.0f;
float escalaSx = 1.0f, escalaSy = 1.0f;
bool  calibrado = false;

uint32_t ultimaimpressaoMs = 0;

void escreverRegistrador(uint8_t reg, uint8_t valor) {
  Wire.beginTransmission(HMC5883L_ADDR);
  Wire.write(reg);
  Wire.write(valor);
  Wire.endTransmission();
}

/**
 * Configura o HMC5883L para operacao normal continua:
 * CRA = 0x70 (Media de 8 amostras, Taxa de 15 Hz, Polarizacao normal)
 * CRB = 0x20 (Faixa +-1.3 Gauss, 1090 LSb/Gauss)
 * MODE = 0x00 (Modo de Medicao Continua)
 */
void configurarModoNormal() {
  escreverRegistrador(REG_CRA,  0x70);
  escreverRegistrador(REG_CRB,  GANHO_CRB_HEX);
  escreverRegistrador(REG_MODE, 0x00);
  delay(10); // Tempo de estabilizacao inicial do ADC (datasheet: 6 ms)
}

/**
 * Verifica a comunicacao I2C e valida a assinatura ROM 'H','4','3' do HMC5883L
 */
bool inicializarHMC5883L() {
  Wire.beginTransmission(HMC5883L_ADDR);
  if (Wire.endTransmission() != 0) {
    // Verifica se ha um variante QMC5883L (0x0D) conectado por engano
    Wire.beginTransmission(QMC5883L_ALT_ADDR);
    if (Wire.endTransmission() == 0) {
      Serial.println(F("[ALERTA] Dispositivo detectado em 0x0D (clone QMC5883L / DA5883), nao em 0x1E!"));
    }
    return false;
  }

  // Le os 3 registradores de identificacao (0x0A, 0x0B, 0x0C)
  Wire.beginTransmission(HMC5883L_ADDR);
  Wire.write(REG_IDA);
  Wire.endTransmission(false);

  if (Wire.requestFrom(HMC5883L_ADDR, (uint8_t)3) == 3) {
    char idA = (char)Wire.read();
    char idB = (char)Wire.read();
    char idC = (char)Wire.read();
    Serial.print(F("[OK] Assinatura de silicio HMC5883L lida em 0x1E: '"));
    Serial.print(idA); Serial.print(idB); Serial.print(idC);
    Serial.println(F("' (Esperado: 'H43')"));
  }

  configurarModoNormal();
  return true;
}

/**
 * Le os 6 registradores de saida (0x03..0x08) respeitando a ordem X, Z, Y
 * Retorna false caso ocorra falha I2C ou saturacao magnetica (-4096)
 */
bool lerCampoGauss(float &bx, float &by, float &bz, bool &saturado) {
  saturado = false;

  Wire.beginTransmission(HMC5883L_ADDR);
  Wire.write(REG_DATA_X);
  if (Wire.endTransmission(false) != 0) {
    return false;
  }

  // Obrigatorio ler todos os 6 bytes para liberar a trava LOCK do HMC5883L
  if (Wire.requestFrom(HMC5883L_ADDR, (uint8_t)6) != 6) {
    return false;
  }

  int16_t rawX = (int16_t)((Wire.read() << 8) | Wire.read());
  int16_t rawZ = (int16_t)((Wire.read() << 8) | Wire.read()); // Ordem fisica: Z vem antes de Y!
  int16_t rawY = (int16_t)((Wire.read() << 8) | Wire.read());

  // Codigo -4096 (0xF000) indica overflow/saturacao do ADC de 12 bits em algum canal
  if (rawX == -4096 || rawY == -4096 || rawZ == -4096) {
    saturado = true;
    return false;
  }

  bx = (float)rawX / GANHO_LSB_GAUSS;
  by = (float)rawY / GANHO_LSB_GAUSS;
  bz = (float)rawZ / GANHO_LSB_GAUSS;
  return true;
}

/**
 * Converte o angulo em graus (0..360) para o ponto cardeal/colateral correspondente
 */
const char* obterPontoCardeal(float azimute) {
  const char* rosa[8] = {"N (Norte)", "NE (Nordeste)", "L (Leste)", "SE (Sudeste)",
                         "S (Sul)", "SO (Sudoeste)", "O (Oeste)", "NO (Noroeste)"};
  uint8_t idx = (uint8_t)floorf((azimute + 22.5f) / 45.0f) % 8;
  return rosa[idx];
}

/**
 * Rotina interativa de 15 segundos para calibracao Hard-Iron e Soft-Iron no plano X-Y
 */
void executarCalibracaoPlana() {
  Serial.println(F("\n======================================================================"));
  Serial.println(F("[CALIBRACAO] Gire o modulo lentamente em 360 graus no plano horizontal"));
  Serial.println(F("             durante os proximos 15 segundos..."));
  Serial.println(F("======================================================================"));

  float minX =  1000.0f, maxX = -1000.0f;
  float minY =  1000.0f, maxY = -1000.0f;
  float minZ =  1000.0f, maxZ = -1000.0f;

  uint32_t inicioMs = millis();
  uint16_t amostrasValidas = 0;

  while (millis() - inicioMs < 15000UL) {
    float bx, by, bz;
    bool sat;
    if (lerCampoGauss(bx, by, bz, sat)) {
      if (bx < minX) minX = bx;
      if (bx > maxX) maxX = bx;
      if (by < minY) minY = by;
      if (by > maxY) maxY = by;
      if (bz < minZ) minZ = bz;
      if (bz > maxZ) maxZ = bz;
      amostrasValidas++;
    }
    delay(70); // Sincronizado com taxa de 15 Hz (~67 ms)
  }

  if (amostrasValidas < 20) {
    Serial.println(F("[ERRO] Amostras insuficientes durante a calibracao."));
    return;
  }

  // Calculo dos offsets Hard-Iron
  offsetBx = (maxX + minX) * 0.5f;
  offsetBy = (maxY + minY) * 0.5f;
  offsetBz = (maxZ + minZ) * 0.5f;

  // Calculo dos fatores de escala Soft-Iron no plano horizontal
  float semiEixoX = (maxX - minX) * 0.5f;
  float semiEixoY = (maxY - minY) * 0.5f;
  float raioMedio = (semiEixoX + semiEixoY) * 0.5f;

  escalaSx = (semiEixoX > 0.01f) ? (raioMedio / semiEixoX) : 1.0f;
  escalaSy = (semiEixoY > 0.01f) ? (raioMedio / semiEixoY) : 1.0f;
  calibrado = true;

  Serial.println(F("[SUCESSO] Parametros Hard-Iron e Soft-Iron calculados:"));
  Serial.print(F(" -> Offset Hard-Iron (Gauss): bx = ")); Serial.print(offsetBx, 4);
  Serial.print(F(" | by = ")); Serial.print(offsetBy, 4);
  Serial.print(F(" | bz = ")); Serial.println(offsetBz, 4);
  Serial.print(F(" -> Escala Soft-Iron:         Sx = ")); Serial.print(escalaSx, 4);
  Serial.print(F(" | Sy = ")); Serial.println(escalaSy, 4);
}

/**
 * Executa o Autoteste Interno (Self-Test) excitando a bobina interna de +1.16G (X,Y) e +1.08G (Z)
 * na escala recomendada pela Honeywell (CRB = 0xA0 -> Ganho = 390 LSb/G, faixa +-4.7G):
 * Limites aprovados pelo datasheet: +243 a +575 LSb nos 3 eixos!
 */
void executarAutotesteInterno() {
  Serial.println(F("\n[AUTOTESTE] Ativando fonte interna de polarizacao positiva (+1.16G X/Y, +1.08G Z)..."));

  escreverRegistrador(REG_CRA,  0x71); // 8 amostras, 15 Hz, Positive Bias (MS0 = 1)
  escreverRegistrador(REG_CRB,  0xA0); // Ganho = 5 (+-4.7 Gauss -> 390 LSb/Gauss)
  escreverRegistrador(REG_MODE, 0x00); // Modo continuo para estabilizar pulso
  delay(70);

  // Descarta a primeira leitura (conversao anterior) e captura a segunda estabilizada
  float dummyX, dummyY, dummyZ;
  bool sat;
  lerCampoGauss(dummyX, dummyY, dummyZ, sat);
  delay(70);

  Wire.beginTransmission(HMC5883L_ADDR);
  Wire.write(REG_DATA_X);
  Wire.endTransmission(false);
  Wire.requestFrom(HMC5883L_ADDR, (uint8_t)6);

  int16_t stX = (int16_t)((Wire.read() << 8) | Wire.read());
  int16_t stZ = (int16_t)((Wire.read() << 8) | Wire.read());
  int16_t stY = (int16_t)((Wire.read() << 8) | Wire.read());

  bool aprovado = (stX >= 243 && stX <= 575) &&
                  (stY >= 243 && stY <= 575) &&
                  (stZ >= 243 && stZ <= 575);

  Serial.print(F(" -> Contagens brutas Self-Test (esperado 243..575): X="));
  Serial.print(stX); Serial.print(F(" | Y=")); Serial.print(stY);
  Serial.print(F(" | Z=")); Serial.println(stZ);
  Serial.println(aprovado
    ? F("[APROVADO] Pontes AMR X, Y e Z dentro das tolerancias de fabrica da Honeywell!")
    : F("[AVISO] Contagem fora da janela nominal (afaste imas externos e repita)."));

  // Restaura operacao normal em +-1.3 Gauss
  configurarModoNormal();
}

void setup() {
  Serial.begin(115200);
  delay(500);

  #if defined(ESP32)
    Wire.begin(21, 22); // SDA = GPIO 21, SCL = GPIO 22 no ESP32
  #else
    Wire.begin();       // A4 (SDA) e A5 (SCL) no Arduino Uno/Nano
  #endif
  Wire.setClock(400000UL); // Barramento I2C em Fast Mode (400 kHz)

  Serial.println(F("\n======================================================================"));
  Serial.println(F("  MODULO BUSSOLA 3 EIXOS GY-271 HMC5883L (SKU: RB0670) - CONSOLE I2C"));
  Serial.println(F("  Comandos: [C] Calibrar Hard/Soft-Iron (15s) | [T] Autoteste Interno"));
  Serial.println(F("======================================================================"));

  if (!inicializarHMC5883L()) {
    Serial.println(F("[ERRO CRITICO] HMC5883L nao respondeu no endereco I2C 0x1E!"));
    Serial.println(F(" -> Verifique VCC (3.3V/5V), GND, SCL e SDA."));
    while (true) {
      delay(1000);
    }
  }
}

void loop() {
  // Processa comandos interativos no Monitor Serial
  if (Serial.available() > 0) {
    char cmd = toupper(Serial.read());
    if (cmd == 'C') {
      executarCalibracaoPlana();
    } else if (cmd == 'T') {
      executarAutotesteInterno();
    }
  }

  // Leitura periodica nao-bloqueante a cada 250 ms
  if (millis() - ultimaimpressaoMs >= 250UL) {
    ultimaimpressaoMs = millis();

    float bx, by, bz;
    bool saturado = false;

    if (!lerCampoGauss(bx, by, bz, saturado)) {
      if (saturado) {
        Serial.println(F("[SATURACAO ADC -4096] Campo magnetico > +-1.3 Gauss! Afaste imas ou reduza o ganho em CRB."));
      } else {
        Serial.println(F("[FALHA I2C] Erro de leitura nos registradores 0x03..0x08."));
      }
      return;
    }

    // Aplica compensacao Hard-Iron e Soft-Iron
    float bxCal = (bx - offsetBx) * escalaSx;
    float byCal = (by - offsetBy) * escalaSy;
    float bzCal = (bz - offsetBz);

    // Modulo total do vetor campo magnetico em microteslas (1 G = 100 uT)
    float moduloUt = sqrtf(bxCal * bxCal + byCal * byCal + bzCal * bzCal) * 100.0f;

    // Calculo do Azimute Magnetico e correcao da Declinacao Geografica
    float headingRad = atan2f(byCal, bxCal);
    float headingGraus = (headingRad * 180.0f / PI) + DECLINACAO_MAG_GRAUS;

    if (headingGraus < 0.0f)    headingGraus += 360.0f;
    if (headingGraus >= 360.0f) headingGraus -= 360.0f;

    Serial.print(calibrado ? F("[CAL] ") : F("[RAW] "));
    Serial.print(F("Bx: ")); Serial.print(bxCal * 100.0f, 1);
    Serial.print(F(" uT | By: ")); Serial.print(byCal * 100.0f, 1);
    Serial.print(F(" uT | Bz: ")); Serial.print(bzCal * 100.0f, 1);
    Serial.print(F(" uT | |B|: ")); Serial.print(moduloUt, 1);
    Serial.print(F(" uT | Azimute: ")); Serial.print(headingGraus, 1);
    Serial.print(F("° -> "));
    Serial.println(obterPontoCardeal(headingGraus));
  }
}

Exemplo 2: Integração Padronizada com a Biblioteca Oficial Adafruit_HMC5883_Unified

Quando o projeto integra múltiplos sensores sob a abstração unificada de eventos no Sistema Internacional de Unidades ($\mu\text{T}$, $\text{m/s}^2$, $\text{rad/s}$), utilize as bibliotecas consagradas Adafruit HMC5883 Unified e Adafruit Unified Sensor (instaláveis diretamente pelo Library Manager da Arduino IDE):

/**
 * ============================================================================
 * Projeto: Leitura Vetorial em Microteslas (uT) com Adafruit Unified Sensor
 * Bibliotecas Requeridas no Library Manager da Arduino IDE:
 *   1. "Adafruit HMC5883 Unified" (por Adafruit)
 *   2. "Adafruit Unified Sensor"  (por Adafruit)
 * ============================================================================
 */

#include <Arduino.h>
#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_HMC5883_U.h>

// Instancia o driver atribuindo um ID unico ao sensor (ex.: 27101)
Adafruit_HMC5883_Unified mag = Adafruit_HMC5883_Unified(27101);

// Declinacao magnetica em radianos (Ex.: -21.6 graus = -0.3770 rad)
const float DECLINACAO_RAD = -21.6f * (PI / 180.0f);

void exibirMetadadosSensor() {
  sensor_t s;
  mag.getSensor(&s);
  Serial.println(F("--- Metadados Adafruit Unified Sensor ---"));
  Serial.print(F("Sensor:       ")); Serial.println(s.name);
  Serial.print(F("Valor Maximo: ")); Serial.print(s.max_value); Serial.println(F(" uT"));
  Serial.print(F("Resolucao:    ")); Serial.print(s.resolution); Serial.println(F(" uT"));
  Serial.println(F("-----------------------------------------"));
}

void setup() {
  Serial.begin(115200);
  delay(400);

  #if defined(ESP32)
    Wire.begin(21, 22);
  #endif

  if (!mag.begin()) {
    Serial.println(F("[ERRO] Nenhum HMC5883L detectado em 0x1E! Revise a fiacao."));
    while (true) {
      delay(1000);
    }
  }

  // Define escala de ganho (+-1.3 Gauss padrao)
  mag.setMagGain(HMC5883_MAGGAIN_1_3);
  exibirMetadadosSensor();
}

void loop() {
  sensors_event_t event;
  mag.getEvent(&event); // Retorna componentes ja convertidas em microteslas (uT)

  float azimuteRad = atan2f(event.magnetic.y, event.magnetic.x) + DECLINACAO_RAD;

  if (azimuteRad < 0.0f)       azimuteRad += 2.0f * PI;
  if (azimuteRad > 2.0f * PI)  azimuteRad -= 2.0f * PI;

  float azimuteGraus = azimuteRad * 180.0f / PI;

  Serial.print(F("Campo [uT] -> X: ")); Serial.print(event.magnetic.x, 2);
  Serial.print(F(" | Y: "));            Serial.print(event.magnetic.y, 2);
  Serial.print(F(" | Z: "));            Serial.print(event.magnetic.z, 2);
  Serial.print(F(" | Rumo Verdadeiro: "));
  Serial.print(azimuteGraus, 1);
  Serial.println(F(" graus"));

  delay(300);
}

Projetos

Para integrar o Módulo Bússola 3 Eixos GY-271 HMC5883L em sistemas completos de telemetria sem fio, fusão inercial ou controle automatizado de posicionamento azimutal, consulte os projetos práticos e guias complementares disponíveis no blog da RoboBuilders:

• Painel Web de Diagnóstico para ESP32: Projeto completo com servidor HTTP embarcado e interface responsiva em tempo real no ESP32, ideal para exibir uma rosa dos ventos digital via Wi-Fi, monitorar o vetor magnético $(B_x, B_y, B_z)$ remotamente e disparar rotinas de calibração Hard-Iron pelo navegador em robôs móveis.
• Painel Web para Placa ESP32 com 8 Relés de 30A (RB2553): Arquitetura de código aberto para acionamento de potência via ESP32 que, combinada à leitura de azimute do GY-271 nos pinos I²C (GPIO 21 e GPIO 22), permite construir controladores industriais de rastreamento solar (Solar Tracker Leste-Oeste) e posicionadores motorizados de antenas direcionais.
• Acelerômetro e Giroscópio 3 Eixos MPU-6050: Manual Técnico Completo: Referência técnica essencial para acoplar o MPU-6050 (0x68) em paralelo ao mesmo barramento I²C do GY-271 (0x1E), formando uma unidade de medida inercial de 9 graus de liberdade (9-DOF) com compensação matemática de inclinação (Roll e Pitch).

Conclusão

Neste manual técnico do Módulo Bússola 3 Eixos GY-271 HMC5883L (RB0670), foram apresentados os fundamentos físicos, elétricos e algorítmicos necessários para obter medições confiáveis de orientação magnética:

• Arquitetura magnetorresistiva AMR e especificações elétricas: Operação baseada no CI Honeywell HMC5883L (L883) com conversor ADC interno de $12\,\text{bits}$, consumo ultrabaixo ($100\,\mu\text{A}$ no núcleo), 8 faixas programáveis entre $\pm 0{,}88\,\text{Gauss}$ e $\pm 8{,}1\,\text{Gauss}$ e regulador LDO integrado compatível com $3{,}0\,\text{VDC}$ a $5{,}0\,\text{VDC}$.
• Mapeamento de hardware e protocolo I²C (0x1E): Detalhamento dos 5 terminais da placa (VCC, GND, SCL, SDA, DRDY), compartilhamento de barramento a $400\,\text{kHz}$ com Arduino e ESP32, atenção obrigatória à sequência de registradores X, Z, Y (0x03–0x08) e leitura integral dos 6 bytes para evitar o travamento por LOCK.
• Boas práticas de montagem não magnética: Uso indispensável de espaçadores/parafusos de Nylon ou latão e distanciamento físico em relação a motores DC, alto-falantes, baterias revestidas em aço e condutores de alta corrente.
• Modelagem matemática e calibração em campo: Compensação das distorções Hard-Iron e Soft-Iron no chassi definitivo, soma da declinação magnética regional brasileira ($\delta_{\text{mag}}$), projeção horizontal para plataformas inclinadas e validação das pontes AMR pelo autoteste interno da Honeywell.

Aplicando criteriosamente o isolamento mecânico contra interferências ferromagnéticas e a rotina de calibração plana descritos neste guia, o módulo GY-271 HMC5883L entrega referência absoluta de rumo estável e precisa para veículos autônomos, instrumentação geofísica e sistemas de automação direcional.

Solução de problemas

Olá! Sou o assistente técnico da RoboBuilders. Descreva seu problema com o Módulo Bússola 3 Eixos GY-271 HMC5883L: Manual Técnico Completo e eu ajudarei a encontrar a solução.

Enviar

O assistente usa IA e pode errar. Confirme informações críticas no datasheet oficial do fabricante.