Aprender

La función map() de Arduino, en una perilla que puedes girar

Principiante

O mira todas las lecciones.

  • 526componentes en el banco de trabajo
  • 46placas funcionando ahora
  • 1.00xtiempo real, en todas las placas
Arduino Uno: una perilla en A0 atenúa el LED del pin 9en vivo0.000 s 0.00x
Haz clic para abrirlo en el editor
map() convierte los 0 a 1023 de la perilla en los 0 a 255 del LED. El monitor serie imprime ambos.

map(value, fromLow, fromHigh, toLow, toHigh) re-scales a number from one range to another. Its most common job is the line map(analogRead(A0), 0, 1023, 0, 255), which turns a knob’s reading into an LED brightness: 0 stays 0, 1023 becomes 255, and everything in between lands in proportion.

El circuito de arriba es exactamente eso: un potenciómetro en A0 y un LED en el pin 9 de un Uno. Presiona Ejecutar y gira la perilla. Con la perilla a la mitad, el monitor serie imprime una lectura de 511 y un brillo de 127. Gírala hasta el tope y imprime 1023 y 255, hasta el otro tope y 0 y 0, y el LED lo sigue.

Ese es el resultado rápido. El resto de esta página son las cuatro cosas que map() hace y que sorprenden a la gente: redondea hacia abajo, no acota, cuenta hacia atrás sin problema, y solo trabaja con números enteros. Cada una se ejecutó en un Uno en Mokxi, y los números de abajo son lo que imprimió.

¿Quieres la versión paso a paso? La lección "Leer un voltaje" recorre esto con puntos de control.

Abrir la lección

El sketch, y los cinco números

The first number is the value to convert. The next two are the range it comes from, and the last two are the range you want. So map(reading, 0, 1023, 0, 255) reads as "reading, which runs from 0 to 1023, scaled to run from 0 to 255". For a servo you would write map(reading, 0, 1023, 0, 180), and the knob at 512 gives 90 degrees.

El sketch imprime solo cuando la lectura se ha movido más de 8, así una perilla quieta no llena el monitor. Cambia el último 255 por 50 y presiona Ejecutar otra vez: el LED nunca pasa de un brillo tenue, porque ahora toda la perilla se mapea a 0 a 50.

firmware/uno/examples/sfpot (el sketch que corre arriba)
const int KNOB = A0;
const int LED = 9;

int shown = -1;

void setup() {
  pinMode(LED, OUTPUT);
  Serial.begin(9600);
  Serial.println("Mokxi Uno: knob on A0, LED on pin 9");
}

void loop() {
  int reading = analogRead(KNOB);
  int brightness = map(reading, 0, 1023, 0, 255);
  analogWrite(LED, brightness);
  if (abs(reading - shown) > 8) {
    shown = reading;
    Serial.print("reading ");
    Serial.print(reading);
    Serial.print("  brightness ");
    Serial.println(brightness);
  }
  delay(20);
}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Cómo funciona map() por dentro

No tiene nada escondido. map() es una línea de aritmética con números enteros, y la referencia de Arduino la imprime completa. Resta el piso del primer rango, multiplica por el tamaño del segundo rango, divide entre el tamaño del primero, y suma el piso del segundo.

Compilamos esa función con otro nombre y la comparamos contra la map() integrada para cada lectura de 0 a 1023, hacia 0 a 255, 0 a 180 y 255 a 0. Cada respuesta coincidió. Conocer la fórmula explica cada sorpresa de abajo: la división descarta el residuo, y nada en ninguna parte verifica que la respuesta esté dentro del rango.

map(), tal como la da la referencia de Arduino
long map(long x, long in_min, long in_max, long out_min, long out_max) {
  return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
}

Redondea hacia abajo, así que el valor máximo es raro

La división entera descarta la fracción. map(512, 0, 1023, 0, 255) es 127.6 en una calculadora y 127 en la placa. map(1022, 0, 1023, 0, 255) es 254.75, y la placa dice 254. Solo una lectura de exactamente 1023 da 255.

Lo contamos, pasando cada lectura de 0 a 1023 por map() en el Uno. Cinco lecturas dan 0, la mayoría de las salidas reciben cuatro lecturas cada una, y 255 recibe una. En un potenciómetro real, con un poco de ruido en el cursor, el LED rara vez quedará a brillo máximo. Eso suele estar bien. Cuando no lo está, divide entre cuatro: reading / 4, que es lo mismo que map(reading, 0, 1024, 0, 256). Así cada salida de 0 a 255 recibe exactamente cuatro lecturas, 512 da 128, y 1023 da 255, nunca 256.

No acota: usa constrain()

map() responde sin problema fuera del rango que le diste. Digamos que calibraste un sensor de luz y viste que lee 200 en la oscuridad y 800 a la luz del día, así que escribiste map(reading, 200, 800, 0, 100) para un porcentaje. Bajo el sol fuerte lee 900, y el sketch dice 116 por ciento. Dale 1200 en un rango de 0 a 1023 y obtienes 299, que no es un brillo que analogWrite() esté hecho para recibir.

La solución es una llamada más. constrain(map(reading, 200, 800, 0, 100), 0, 100) dio 100 para la misma lectura de 900. Mantén los dos juntos siempre que la entrada pueda pasarse de los extremos que mediste, que con cualquier sensor real es siempre.

Mapear y luego acotar
void setup() {
  Serial.begin(9600);
  int reading = 900;
  Serial.println(map(reading, 200, 800, 0, 100));
  Serial.println(constrain(map(reading, 200, 800, 0, 100), 0, 100));
}

void loop() {
}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Hacia atrás y por debajo de cero

Cambia los últimos dos números y el rango va en sentido contrario. map(300, 0, 1023, 255, 0) dio 181, así que subir la perilla atenúa el LED. Esa es la solución fácil para un potenciómetro cableado al revés, o un sensor de luz que debe encender una lámpara cuando oscurece.

Negative numbers work too. map(512, 0, 1023, -40, 125) gave 42, which is how a sensor’s 0 to 5 V output becomes -40 to 125 degrees. Below zero, the rounding goes toward zero rather than down: map(-10, 0, 1023, 0, 255) gave -2, not -3.

Por qué map() usa long, y por qué desaparecen los decimales

Haz tú la aritmética con un int y sale mal. En un Uno un int es de 16 bits y solo llega hasta 32767. int a = 1000; y luego a * 180 / 1023 imprimió -16, porque 180000 no cabe y se desbordó antes de la división. map(1000, 0, 1023, 0, 180) imprimió 175, porque map() hace su multiplicación en un long de 32 bits.

map() solo acepta números enteros. map(2.7, 0, 10, 0, 100) imprimió 20, porque 2.7 se truncó a 2 al entrar, y la pestaña de compilación advirtió: implicit conversion from 'double' to 'long' changes value from 2.7 to 2. Para decimales, escribe la misma fórmula con floats. La versión de abajo imprimió 27.00 para 2.7, y 2.50 para una lectura de 512 escalada a 0 a 5 volts.

Un map() para floats
float mapFloat(float x, float inMin, float inMax, float outMin, float outMax) {
  return (x - inMin) * (outMax - outMin) / (inMax - inMin) + outMin;
}

void setup() {
  Serial.begin(9600);
  Serial.println(mapFloat(2.7, 0, 10, 0, 100));
  Serial.println(mapFloat(512, 0, 1023, 0, 5));
}

void loop() {
}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Abre este circuito en el editor. Arduino Uno: una perilla en A0 atenúa el LED del pin 9, cableado como corre al inicio de esta página. Cambia un componente o un valor y ejecútalo de nuevo.

Abrir el circuito

Preguntas

¿Acaso el map() de Arduino limita el resultado?

No. Un valor fuera del primer rango da una respuesta fuera del segundo: una lectura de 900 mapeada de 200 a 800 hacia 0 a 100 da 116. Envuélvela en constrain(), como en constrain(map(x, 200, 800, 0, 100), 0, 100).

¿Por qué map(x, 0, 1023, 0, 255) casi nunca llega a 255?

Como map() redondea hacia abajo, solo una lectura de exactamente 1023 da 255. Cinco lecturas dan 0 y la mayoría de las salidas reciben cuatro. Divide la lectura entre 4 si quieres que cada brillo reciba la misma parte de la perilla.

¿Puede map() usar decimales?

No. Sus argumentos y su respuesta son long, así que 2.7 se vuelve 2 antes de empezar. Escribe la misma fórmula con argumentos float, como hace la función mapFloat() de esta página, cuando necesites fracciones.

¿Cómo invierto un rango con map()?

Intercambia los últimos dos números: map(reading, 0, 1023, 255, 0) da 255 en la parte baja de la perilla y 0 en la parte alta. El primer rango se puede invertir de la misma manera.

¿Cuál es la diferencia entre map() y constrain()?

map() cambia la escala de un número. constrain() deja la escala tal cual e impide que un número se pase de los dos límites que le das. A menudo se usan juntos, primero map().

¿Cuál es la fórmula de la función map() de Arduino?

(value - fromLow) * (toHigh - toLow) / (fromHigh - fromLow) + toLow, calculado con números enteros y descartando el residuo. Así, map(1000, 0, 1023, 0, 100) es 97 y map(512, 0, 1023, 0, 100) es 50, que es lo que imprimió un Uno aquí.

Fuentes

De dónde vienen los datos de esta página

Ármalo en la vida real

Abre el editor, cambia un valor y mira cómo cambia el número con él. Nada que instalar y sin necesidad de cuenta.