BASICAIO - LEEME_MODULOS_ARDUINO.txt
======================================
Si solo se utilizarán entradas digitales y analógicas puede subir el código de ejemplo provisto

Este archivo indica qué librerías instalar en Arduino IDE para hacer extensión de las funcionalidades con nuevos sensores.
Los nuevos sensores se agregan como módulos al archivo basicaio_tools.h (no hace falta modificar el archivo .ino)

============================================================
REGLA GENERAL PARA AGREGAR UNA HERRAMIENTA
============================================================

Cada herramienta BASICAIO tiene esta forma:

String nombre_de_la_herramienta() {
  // 1. Leer argumentos si hacen falta:
  // int pin = getIntArg("pin", 13);
  // String texto = getStringArg("texto", "Hola");

  // 2. Ejecutar código Arduino.

  // 3. Devolver un resultado.
  return "OK";
}

REGISTER_TOOL(
  "nombre_de_la_herramienta",
  "Descripción visible desde BASICAIO",
  "{\"type\":\"object\",\"properties\":{}}",
  nombre_de_la_herramienta
)

************************************************************
******** EJEMPLOS DE FICHAS DE HERRAMIENTAS ****************
************************************************************

============================================================
MÓDULO: DS18B20 - SENSOR DE TEMPERATURA ONE WIRE
============================================================

Usar si el proyecto incluye un sensor de temperatura DS18B20.

LIBRERÍAS A INSTALAR:
- OneWire
- DallasTemperature

CONEXIÓN TÍPICA:
- VDD  -> 5V
- GND  -> GND
- DATA -> Pin digital 2

IMPORTANTE:
Agregar una resistencia de 4.7kΩ entre DATA y 5V.

INCLUDES NECESARIOS EN basicaio_tools.h:
#include <OneWire.h>
#include <DallasTemperature.h>

CONFIGURACIÓN GLOBAL:
#define DS18B20_PIN 2

OneWire oneWireBus(DS18B20_PIN);
DallasTemperature ds18b20(&oneWireBus);

DENTRO DE setupTeacherHardware():
ds18b20.begin();

*** FICHA DE HERRAMIENTA ***

String leer_temperatura_ds18b20() {
  ds18b20.requestTemperatures();

  float temperatura = ds18b20.getTempCByIndex(0);

  if (temperatura == DEVICE_DISCONNECTED_C) {
    return "ERROR: sensor DS18B20 no detectado";
  }

  return String(temperatura, 2);
}

REGISTER_TOOL(
  "leer_temperatura_ds18b20",
  "Lee la temperatura en grados Celsius desde un sensor DS18B20 conectado al pin 2",
  "{\"type\":\"object\",\"properties\":{}}",
  leer_temperatura_ds18b20
)


============================================================
MÓDULO: DHT11 / DHT22 - TEMPERATURA Y HUMEDAD
============================================================

Usar si el proyecto incluye sensores DHT11 o DHT22.

LIBRERÍAS A INSTALAR:
- DHT sensor library
- Adafruit Unified Sensor

CONEXIÓN TÍPICA:
- VCC  -> 5V
- GND  -> GND
- DATA -> Pin digital 2

INCLUDE NECESARIO EN basicaio_tools.h:
#include <DHT.h>

CONFIGURACIÓN GLOBAL PARA DHT11:
#define DHT_PIN 2
#define DHT_TYPE DHT11

DHT dht(DHT_PIN, DHT_TYPE);

CONFIGURACIÓN GLOBAL PARA DHT22:
#define DHT_PIN 2
#define DHT_TYPE DHT22

DHT dht(DHT_PIN, DHT_TYPE);

DENTRO DE setupTeacherHardware():
dht.begin();

*** FICHA DE HERRAMIENTA *** LEER TEMPERATURA:

String leer_temperatura_dht() {
  float temperatura = dht.readTemperature();

  if (isnan(temperatura)) {
    return "ERROR: no se pudo leer temperatura DHT";
  }

  return String(temperatura, 2);
}

REGISTER_TOOL(
  "leer_temperatura_dht",
  "Lee la temperatura en grados Celsius desde un sensor DHT11 o DHT22",
  "{\"type\":\"object\",\"properties\":{}}",
  leer_temperatura_dht
)

*** FICHA DE HERRAMIENTA *** LEER HUMEDAD:

String leer_humedad_dht() {
  float humedad = dht.readHumidity();

  if (isnan(humedad)) {
    return "ERROR: no se pudo leer humedad DHT";
  }

  return String(humedad, 2);
}

REGISTER_TOOL(
  "leer_humedad_dht",
  "Lee la humedad relativa desde un sensor DHT11 o DHT22",
  "{\"type\":\"object\",\"properties\":{}}",
  leer_humedad_dht
)


============================================================
MÓDULO: SERVO MOTOR
============================================================

Usar si el proyecto incluye servomotores.

LIBRERÍAS A INSTALAR:
- Ninguna librería externa.
- Arduino IDE ya incluye Servo.

INCLUDE NECESARIO EN basicaio_tools.h:
#include <Servo.h>

CONEXIÓN TÍPICA:
- Rojo / VCC      -> 5V externo recomendado
- Marrón / Negro  -> GND
- Naranja / Señal -> Pin digital 9

IMPORTANTE:
Si se usa fuente externa para el servo, unir GND de la fuente con GND del Arduino.

CONFIGURACIÓN GLOBAL:
Servo servo1;
#define SERVO_PIN 9

DENTRO DE setupTeacherHardware():
servo1.attach(SERVO_PIN);

*** FICHA DE HERRAMIENTA ***

String mover_servo() {
  int angulo = getIntArg("angulo", 90);

  if (angulo < 0) angulo = 0;
  if (angulo > 180) angulo = 180;

  servo1.write(angulo);

  return String("Servo movido a ") + String(angulo) + String(" grados");
}

REGISTER_TOOL(
  "mover_servo",
  "Mueve un servomotor a un ángulo entre 0 y 180 grados",
  "{\"type\":\"object\",\"properties\":{\"angulo\":{\"type\":\"integer\",\"description\":\"Ángulo entre 0 y 180\"}},\"required\":[\"angulo\"]}",
  mover_servo
)


============================================================
MÓDULO: SENSOR ULTRASÓNICO HC-SR04
============================================================

Usar si el proyecto incluye un sensor ultrasónico HC-SR04 para medir distancia.

LIBRERÍAS A INSTALAR:
- Ninguna librería externa.

CONEXIÓN TÍPICA:
- VCC  -> 5V
- GND  -> GND
- TRIG -> Pin digital 8
- ECHO -> Pin digital 7

CONFIGURACIÓN GLOBAL:
#define HC_SR04_TRIG_PIN 8
#define HC_SR04_ECHO_PIN 7

DENTRO DE setupTeacherHardware():
pinMode(HC_SR04_TRIG_PIN, OUTPUT);
pinMode(HC_SR04_ECHO_PIN, INPUT);

*** FICHA DE HERRAMIENTA ***

String medir_distancia_hcsr04() {
  digitalWrite(HC_SR04_TRIG_PIN, LOW);
  delayMicroseconds(2);

  digitalWrite(HC_SR04_TRIG_PIN, HIGH);
  delayMicroseconds(10);
  digitalWrite(HC_SR04_TRIG_PIN, LOW);

  long duracion = pulseIn(HC_SR04_ECHO_PIN, HIGH, 30000);

  if (duracion == 0) {
    return "ERROR: sin lectura del sensor HC-SR04";
  }

  float distanciaCm = duracion * 0.0343 / 2.0;

  return String(distanciaCm, 2);
}

REGISTER_TOOL(
  "medir_distancia_hcsr04",
  "Mide distancia en centímetros usando un sensor ultrasónico HC-SR04",
  "{\"type\":\"object\",\"properties\":{}}",
  medir_distancia_hcsr04
)


============================================================
MÓDULO: BUZZER
============================================================

Usar si el proyecto incluye un buzzer o zumbador.

LIBRERÍAS A INSTALAR:
- Ninguna librería externa.

CONEXIÓN TÍPICA:
- Positivo -> Pin digital 6
- Negativo -> GND

CONFIGURACIÓN GLOBAL:
#define BUZZER_PIN 6

DENTRO DE setupTeacherHardware():
pinMode(BUZZER_PIN, OUTPUT);

*** FICHA DE HERRAMIENTA ***

String sonar_buzzer() {
  int frecuencia = getIntArg("frecuencia", 1000);
  int duracion = getIntArg("duracion", 500);

  tone(BUZZER_PIN, frecuencia, duracion);

  return String("Buzzer sonando a ") + String(frecuencia) + String(" Hz");
}

REGISTER_TOOL(
  "sonar_buzzer",
  "Hace sonar un buzzer indicando frecuencia y duración",
  "{\"type\":\"object\",\"properties\":{\"frecuencia\":{\"type\":\"integer\"},\"duracion\":{\"type\":\"integer\"}},\"required\":[\"frecuencia\",\"duracion\"]}",
  sonar_buzzer
)


============================================================
MÓDULO: LCD 16x2 CON I2C
============================================================

Usar si el proyecto incluye una pantalla LCD 16x2 con adaptador I2C.

LIBRERÍAS A INSTALAR:
- LiquidCrystal I2C

En algunas instalaciones puede aparecer como:
- LiquidCrystal_I2C

INCLUDE NECESARIO EN basicaio_tools.h:
#include <Wire.h>
#include <LiquidCrystal_I2C.h>

CONEXIÓN TÍPICA:
- VCC -> 5V
- GND -> GND
- SDA -> A4 en Arduino UNO/Nano
- SCL -> A5 en Arduino UNO/Nano

CONFIGURACIÓN GLOBAL:
LiquidCrystal_I2C lcd(0x27, 16, 2);

IMPORTANTE:
Algunos módulos usan dirección 0x3F en lugar de 0x27.

DENTRO DE setupTeacherHardware():
lcd.init();
lcd.backlight();

*** FICHA DE HERRAMIENTA ***

String lcd_escribir() {
  String texto = getStringArg("texto", "Hola BASICAIO");
  int fila = getIntArg("fila", 0);

  if (fila < 0) fila = 0;
  if (fila > 1) fila = 1;

  lcd.setCursor(0, fila);
  lcd.print("                ");
  lcd.setCursor(0, fila);
  lcd.print(texto);

  return "Texto enviado al LCD";
}

REGISTER_TOOL(
  "lcd_escribir",
  "Escribe texto en una pantalla LCD 16x2 con I2C",
  "{\"type\":\"object\",\"properties\":{\"texto\":{\"type\":\"string\"},\"fila\":{\"type\":\"integer\"}},\"required\":[\"texto\"]}",
  lcd_escribir
)


============================================================
MÓDULO: LDR - SENSOR DE LUZ
============================================================

Usar si el proyecto incluye un sensor LDR conectado a una entrada analógica.

LIBRERÍAS A INSTALAR:
- Ninguna librería externa.

CONEXIÓN TÍPICA:
- Usar divisor resistivo.
- Señal al pin A0.

CONFIGURACIÓN GLOBAL:
#define LDR_PIN A0

DENTRO DE setupTeacherHardware():
No requiere configuración especial.

*** FICHA DE HERRAMIENTA ***

String leer_luz_ldr() {
  int valor = analogRead(LDR_PIN);

  return String(valor);
}

REGISTER_TOOL(
  "leer_luz_ldr",
  "Lee el valor analógico de un sensor de luz LDR conectado a A0",
  "{\"type\":\"object\",\"properties\":{}}",
  leer_luz_ldr
)


============================================================
MÓDULO: POTENCIÓMETRO
============================================================

Usar si el proyecto incluye un potenciómetro conectado a una entrada analógica.

LIBRERÍAS A INSTALAR:
- Ninguna librería externa.

CONEXIÓN TÍPICA:
- Extremo 1 -> 5V
- Extremo 2 -> GND
- Pin central -> A0

CONFIGURACIÓN GLOBAL:
#define POT_PIN A0

DENTRO DE setupTeacherHardware():
No requiere configuración especial.

*** FICHA DE HERRAMIENTA ***

String leer_potenciometro() {
  int valor = analogRead(POT_PIN);

  return String(valor);
}

REGISTER_TOOL(
  "leer_potenciometro",
  "Lee el valor analógico de un potenciómetro conectado a A0",
  "{\"type\":\"object\",\"properties\":{}}",
  leer_potenciometro
)


============================================================
MÓDULO: BOTÓN DIGITAL
============================================================

Usar si el proyecto incluye un botón conectado a un pin digital.

LIBRERÍAS A INSTALAR:
- Ninguna librería externa.

CONEXIÓN RECOMENDADA:
- Un lado del botón -> GND
- Otro lado del botón -> Pin digital 4

CONFIGURACIÓN GLOBAL:
#define BOTON_PIN 4

DENTRO DE setupTeacherHardware():
pinMode(BOTON_PIN, INPUT_PULLUP);

*** FICHA DE HERRAMIENTA ***

String leer_boton() {
  int estado = digitalRead(BOTON_PIN);

  if (estado == LOW) {
    return "PRESIONADO";
  }

  return "LIBRE";
}

REGISTER_TOOL(
  "leer_boton",
  "Lee el estado de un botón conectado al pin digital 4 usando INPUT_PULLUP",
  "{\"type\":\"object\",\"properties\":{}}",
  leer_boton
)


============================================================
MÓDULO: RELÉ
============================================================

Usar si el proyecto incluye un módulo relé.

LIBRERÍAS A INSTALAR:
- Ninguna librería externa.

CONEXIÓN TÍPICA:
- VCC -> 5V
- GND -> GND
- IN  -> Pin digital 5

CONFIGURACIÓN GLOBAL:
#define RELE_PIN 5

DENTRO DE setupTeacherHardware():
pinMode(RELE_PIN, OUTPUT);
digitalWrite(RELE_PIN, LOW);

*** FICHA DE HERRAMIENTA *** ENCENDER RELÉ:

String rele_on() {
  digitalWrite(RELE_PIN, HIGH);
  return "Relé encendido";
}

REGISTER_TOOL(
  "rele_on",
  "Activa un módulo relé conectado al pin digital 5",
  "{\"type\":\"object\",\"properties\":{}}",
  rele_on
)

*** FICHA DE HERRAMIENTA *** APAGAR RELÉ:

String rele_off() {
  digitalWrite(RELE_PIN, LOW);
  return "Relé apagado";
}

REGISTER_TOOL(
  "rele_off",
  "Desactiva un módulo relé conectado al pin digital 5",
  "{\"type\":\"object\",\"properties\":{}}",
  rele_off
)




============================================================
NOTAS IMPORTANTES
============================================================

1) Si aparece un error como:
   fatal error: NombreLibreria.h: No such file or directory

   Significa que falta instalar una librería desde el Administrador
   de Bibliotecas de Arduino IDE.

2) Si el programa compila pero el sensor no responde:
   - Revisar conexiones.
   - Revisar alimentación.
   - Revisar el pin definido en el código.
   - En sensores I2C, revisar la dirección I2C.

3) No modificar arduino_mcp.ino salvo indicación del equipo BASICAIO.

4) Las herramientas nuevas deben agregarse en basicaio_tools.h.

5) Para facilitar el uso en clase, se recomienda copiar una ficha completa,
   modificar el nombre, la descripción y el código necesario.


COMO INSTALAR UNA LIBRERÍA EN ARDUINO IDE
========================================

Arduino IDE 1.x / 2.x:

1) Abrir Arduino IDE.
2) Ir a:
   Programa -> Incluir librería -> Administrar bibliotecas...

   En algunas versiones puede aparecer como:
   Sketch -> Include Library -> Manage Libraries...

3) Buscar el nombre de la librería.
4) Instalar la librería indicada.
5) Compilar nuevamente el programa.
