Avanzado

Componentes menos habituales o de uso más técnico.

Expander (expansor de pines)

new five.Expander({ controller, address }). Un chip que añade pines de E/S; se comporta como una mini placa. Otros componentes pueden montarse sobre él.

Opciones: controller (obligatorio; sin él lanza error), address (dirección I2C), bus.

Controllers: MCP23017, MCP23008, PCF8574, PCF8575, PCA9685, PCF8591, MUXSHIELD2, GROVEPI, 74HC595, CD74HC4067, LIS3DH, ADS1115.

Propiedades: HIGH, LOW, isReady, MODES, pins, analogPins, address.

Métodos: provee los de una placa según el chip — pinMode(pin, modo), digitalWrite(pin, valor), digitalRead(pin, cb), analogRead(pin, cb), analogWrite(pin, valor), servoWrite, pwmWrite… Los que el chip no soporta lanzan un error descriptivo.

Estáticos: Expander.get({ address, controller }) (reusa o crea uno), Expander.byAddress(address), Expander.byController(nombre), Expander.hasController(clave).

Eventos: connect, ready, y eventos de lectura por pin (digital-read-<pin>, analog-read-<pin>…).

const exp = new five.Expander({ controller: "MCP23017" });
exp.pinMode(0, exp.MODES.OUTPUT);
exp.digitalWrite(0, exp.HIGH); // enciende el pin 0 del expansor

Board.Virtual (placa virtual)

five.Board.Virtual(expander) crea un objeto “placa” a partir de un Expander (o de unas opciones). Sirve para montar componentes sobre el expansor como si fuera una placa: le pasas esa placa virtual en la opción board del componente. Es la pieza que une un Expander con el resto del catálogo.

const exp = new five.Expander({ controller: "PCF8574" });
const virtual = new five.Board.Virtual(exp);
const led = new five.Led({ pin: 0, board: virtual }); // un LED en el pin 0 del expansor
led.on();

Animation (animación de servos)

new five.Animation(objetivo). Anima uno o varios servos siguiendo una secuencia de fotogramas. El argumento del constructor es el objetivo (un Servo o una colección de servos), no un objeto de opciones.

Métodos (devuelven la animación)

Método	Qué hace
enqueue(segmento)	encola un segmento; si no hay nada corriendo, empieza
play()	reproduce
pause()	pausa manteniendo el progreso
stop()	detiene y vacía la cola
speed(valor)	sin argumento, devuelve la velocidad; con argumento, la fija
next()	pasa al siguiente segmento de la cola

El objeto “segmento” (lo que recibe enqueue)

Clave	Significado
target	servo o colección a animar (default: el objetivo del constructor)
cuePoints	array de puntos de tiempo normalizados 0..1 (default [0, 1])
keyFrames	los valores en cada cuePoint; para colecciones, un array por servo
duration	duración en ms (default 1000)
easing	función de suavizado (default "linear")
loop	repetir en bucle (default false)
loopback	punto de progreso al que volver al repetir (default 0)
metronomic	ir y volver (ping-pong) (default false)
fps	fotogramas por segundo (default 60)
onstart / onpause / onstop / oncomplete / onloop	callbacks de ciclo de vida

Eventos: animation:pause y animation:stop (sin payload). El fin de un segmento o de un bucle se notifica por los callbacks oncomplete/onloop del segmento.

const servo = new five.Servo(9);
const anim = new five.Animation(servo);

anim.enqueue({
  duration: 2000,
  cuePoints: [0, 0.5, 1],   // tres momentos: inicio, mitad, fin
  keyFrames: [0, 180, 90],  // grados en cada momento
  loop: true,
});

GPS

new five.GPS({ pins: { rx, tx }, ... }) o new five.GPS([rx, tx]). Recibe posición de un módulo GPS por puerto serie.

Opciones: pins ({ rx, tx, onOff? }), baud (default 9600), breakout / receiver / chip (modelo del módulo; deriva la configuración), frequency (solo chip MT3339).

Propiedades: latitude, longitude, altitude, speed (m/s), course (rumbo), sat ({ satellites, pdop, hdop, vdop }), time.

Métodos: sendCommand(cadena) (envía un comando NMEA con checksum), restart(coldRestart) y el setter frequency (chip MT3339).

Eventos

Evento	Qué recibe
data	{ latitude, longitude, altitude, speed, course, sat, time }
change	{ latitude, longitude, altitude } (al cambiar la posición)
navigation	{ speed, course } (al cambiar velocidad/rumbo)
sentence	la cadena NMEA recibida
operations / acknowledge / unknown	la cadena de la sentencia correspondiente

const gps = new five.GPS({ pins: { rx: 10, tx: 11 } });
gps.on("change", () => {
  varG.lat = gps.latitude;
  varG.lon = gps.longitude;
});

ReflectanceArray (seguidor de línea)

new five.ReflectanceArray({ emitter, pins, ... }). Array de sensores de reflectancia para seguir una línea.

Opciones: emitter (obligatorio, pin del LED emisor), pins (obligatorio, array de pines de los sensores), freq (ms de muestreo, default 25), autoCalibrate (bool).

Propiedades: values (calibrados), raw (crudos), line (posición estimada de la línea), isOnLine (bool), isCalibrated (bool), sensors (los Sensor), calibration ({ min, max }).

Métodos (devuelven el objeto): enable() / disable() (LED emisor), calibrate() (captura una muestra de calibración; llamar muchas veces sobre claro y oscuro), calibrateUntil(predicado) (calibra hasta que el predicado sea cierto), loadCalibration({ min, max }) (carga una calibración previa).

Eventos: data (array crudo), calibratedData (array calibrado), line (posición), calibrated (sin payload, al terminar una calibración).

const eyes = new five.ReflectanceArray({ emitter: 11, pins: ["A0", "A1", "A2"] });
eyes.enable();
eyes.on("line", (posicion) => {
  varG.linea = posicion; // posición estimada de la línea
});

Sleep

five.Sleep es un módulo, no una clase: five.Sleep.milli(ms) y five.Sleep.micro(us).

Bloquea todo el runtime

Sleep hace una espera ocupada (busy-wait): congela por completo el hilo durante ese tiempo. En el boardCode eso bloquea toda la placa y la telemetría mientras dura. Evítalo: para esperar, usa setTimeout/setInterval, que no bloquean. Se documenta por completitud, pero casi nunca es lo que quieres.

Fn (utilidades)

five.Fn es un espacio de utilidades internas que usan los componentes por dentro; rara vez la necesitas directamente. Incluye, entre otras, debounce y cloneDeep (reexportadas) además de helpers numéricos para mapear, escalar y acotar valores. Para escalar lecturas, lo normal es usar los métodos scale/scaleTo del propio Sensor, no Fn.

bread (la placa)

bread es el objeto de la placa de este thing (no lo creas tú; ya está disponible). La mayoría de las veces no lo necesitas, pero expone algunas utilidades:

Método	Qué hace
bread.loop(ms, cb)	ejecuta cb cada ms; cb recibe una función para detener el bucle
bread.wait(ms, cb)	ejecuta cb una vez tras ms
bread.samplingInterval(ms)	ajusta el intervalo de muestreo de la placa
bread.shiftOut(dataPin, clockPin, bigEndian, valor)	envía un byte por bit-banging

bread.loop/bread.wait se limpian solos en cada recarga, igual que setInterval. Para pines y buses a bajo nivel, usa el objeto board.