Preferencias de usuario

Cuando flasheas un nodo de Meshtastic con el firmware oficial, arranca con una configuración genérica (factory defaults). Si vas a preparar varios nodos iguales, nodos fijos o equipos que no quieres configurar uno a uno por Bluetooth o cable, puedes ahorrar trabajo compilando el firmware con valores por defecto propios.

Meshtastic permite hacerlo mediante el archivo userPrefs.jsonc. Los valores que definas ahí se aplicarán en el primer arranque del nodo o después de un restablecimiento de fábrica.

Esta guía resume el flujo práctico y deja al final una referencia de los parámetros más útiles. Está basada en la documentación de desarrollo de Meshtastic.

Aviso de seguridad

Algunas preferencias afectan directamente a la seguridad del nodo. Por ejemplo, un firmware manipulado podría incluir claves públicas de administración remota de un tercero y darle control sobre tu nodo sin que lo sepas.

Se recomienda no instalar firmwares de origen desconocido o de fuentes en las que no confíes. Compila siempre tu propio firmware a partir del código fuente oficial.

---

1. Clonar el repositorio de Meshtastic

El primer paso es obtener el código fuente del firmware de Meshtastic en tu equipo:

git clone https://github.com/meshtastic/firmware.git
cd firmware
git submodule update --init

tip

Se recomienda trabajar sobre la etiqueta de la versión que desees compilar. Puedes ver todas las versiones publicadas en la lista de etiquetas del repositorio.

git checkout vX.Y.Z.hash
git submodule update --init

---

2. Configurar las preferencias en userPrefs.jsonc

En la raíz del proyecto clonado encontrarás el archivo userPrefs.jsonc. Este fichero usa JSON con comentarios (.jsonc) y sirve para definir los valores por defecto que se incluirán en el firmware durante la compilación.

Para personalizar la configuración, abre el archivo con tu editor preferido (como VSCode) y descomenta/modifica las líneas necesarias.

info

• Todos los valores en userPrefs.jsonc son cadenas de texto (entre comillas), incluso los números y booleanos.
• Las líneas que empiezan por // están comentadas y se ignoran durante la compilación.
• La mayoría de preferencias se aplican únicamente en el primer arranque o tras un restablecimiento de fábrica. Si el nodo ya estaba configurado, borra la configuración antes de probar estos valores.

Ejemplo base para España

Copia solo los valores que necesites y cambia los nombres, coordenadas y claves por los tuyos. Este ejemplo fija región EU 868, preset Long Fast, posición estática y zona horaria peninsular:

{
  // Identidad
  "USERPREFS_CONFIG_OWNER_LONG_NAME": "Nodo Central Madrid",
  "USERPREFS_CONFIG_OWNER_SHORT_NAME": "NCM1",
  "USERPREFS_CONFIG_DEVICE_ROLE": "meshtastic_Config_DeviceConfig_Role_CLIENT",

  // LoRa
  "USERPREFS_CONFIG_LORA_REGION": "meshtastic_Config_LoRaConfig_RegionCode_EU_868",
  "USERPREFS_LORACONFIG_MODEM_PRESET": "meshtastic_Config_LoRaConfig_ModemPreset_LONG_FAST",

  // Posición GPS fija (ejemplo: Puerta del Sol, Madrid)
  "USERPREFS_FIXED_GPS": "true",
  "USERPREFS_FIXED_GPS_LAT": "40.416775",
  "USERPREFS_FIXED_GPS_LON": "-3.703790",
  "USERPREFS_FIXED_GPS_ALT": "657",

  // Clave pública del nodo administrador para administración remota
  "USERPREFS_USE_ADMIN_KEY_0": "{ 0xcd, 0xc0, 0xb4, 0x3c, 0x53, 0x24, 0xdf, 0x13, 0xca, 0x5a, 0xa6, 0x0c, 0x0d, 0xec, 0x85, 0x5a, 0x4c, 0xf6, 0x1a, 0x96, 0x04, 0x1a, 0x3e, 0xfc, 0xbb, 0x8e, 0x33, 0x71, 0xe5, 0xfc, 0xff, 0x3c }",

  // Zona horaria de España peninsular
  "USERPREFS_TZ_STRING": "CET-1CEST,M3.5.0,M10.5.0/3",
}

---

3. Compilar el firmware

Una vez editado y guardado tu archivo userPrefs.jsonc, puedes compilar el firmware de dos formas:

VSCode + PlatformIO

1. Instala VSCode y añade la extensión PlatformIO IDE.
2. Abre la carpeta del firmware clonado desde VSCode (Archivo -> Abrir carpeta).
3. Espera a que PlatformIO inicialice el proyecto y descargue las dependencias necesarias.
4. Abre la Paleta de Comandos (Ctrl+Shift+P en Windows/Linux o Cmd+Shift+P en macOS).
5. Escribe PlatformIO: Pick Project Target y selecciona tu placa.
6. Escribe PlatformIO: Build para iniciar la compilación. También puedes hacerlo desde el panel lateral de PlatformIO seleccionando el modelo exacto de tu dispositivo (Target) y haciendo clic en Build.

Terminal (CLI)

Primero debes tener instalado PlatformIO Core CLI.

1. Abre una terminal y sitúate en la raíz del repositorio.
2. Si no conoces el nombre del target exacto de tu placa, puedes listar los entornos disponibles ejecutando:

   pio project config | grep -e "^env:"

   
3. Ejecuta el comando de compilación especificando el target de tu hardware con la opción -e:

   pio run -e DEVICE_TARGET

   Ejemplo para un chip nRF52 DIY:

   pio run -e nrf52_promicro_diy_tcxo

   

---

4. Flashear / Subir el firmware al nodo

Cuando la compilación se complete con éxito, tendrás listo el binario personalizado. Ahora solo queda flashearlo al dispositivo:

VSCode + PlatformIO

Conecta el nodo a tu ordenador por cable USB y ejecuta la tarea de subida desde el panel de tareas de PlatformIO, o usa la paleta de comandos buscando: PlatformIO: Upload

Terminal (CLI)

Conecta tu nodo por USB y ejecuta el comando indicando el target y el parámetro de subida (-t upload):

pio run -e DEVICE_TARGET -t upload

Ejemplo:

pio run -e nrf52_promicro_diy_tcxo -t upload

aviso

Asegúrate de que el puerto serie de tu nodo no esté ocupado por otra aplicación (como un monitor serie o el flasheador web de Meshtastic en el navegador) antes de lanzar el comando de subida.

---

5. Comprobar que se han aplicado los valores

Después de flashear, enciende el nodo y revisa desde la app o la CLI que la configuración esperada se ha cargado correctamente.

• Comprueba el nombre largo y el nombre corto del nodo.
• Comprueba la región LoRa y el preset de módem.
• Si has definido posición fija, comprueba que aparece la latitud, longitud y altitud esperadas.
• Si has añadido una clave de administración remota, comprueba que aparece en la sección de seguridad del nodo. Puedes ampliar este punto en la guía de administración remota.

Si el nodo ya había arrancado antes con otra configuración, haz un restablecimiento de fábrica y vuelve a probar. Muchas preferencias de userPrefs.jsonc no sobreescriben valores ya guardados.

---

6. Referencia de preferencias disponibles

Qué NO se puede configurar con userPrefs

Antes de depender de este fichero, ten claras estas limitaciones:

• No se pueden definir presets de LoRa personalizados. Solo puedes elegir entre los presets predefinidos de la tabla que verás más abajo. Si necesitas valores personalizados de ancho de banda, spreading factor o coding rate, tendrás que configurarlos en tiempo de ejecución con la CLI o la app móvil.
• No se pueden inyectar claves privadas. Las claves de administración remota (USERPREFS_USE_ADMIN_KEY_*) corresponden siempre a la clave pública del nodo administrador, nunca a una clave privada.
• Algunos roles están restringidos por el firmware. En las versiones actuales, la familia ROUTER, REPEATER y LOST_AND_FOUND no se puede forzar desde userPrefs. Comprueba el userPrefs.jsonc de la versión exacta que vayas a compilar, porque esta lista puede cambiar.
• Solo se pueden preconfigurar hasta 3 canales (índices 0, 1 y 2), aunque el protocolo admite hasta 8.

Qué se puede configurar

Identidad del nodo

Parámetro	Descripción
USERPREFS_CONFIG_OWNER_LONG_NAME	Nombre largo del nodo, el que aparece en la lista de nodos.
USERPREFS_CONFIG_OWNER_SHORT_NAME	Nombre corto, de 3 a 4 caracteres (ej. "NCM1").
USERPREFS_CONFIG_DEVICE_ROLE	Rol del nodo. Por defecto es CLIENT (ver tabla de roles abajo).
USERPREFS_FIXED_BLUETOOTH	PIN numérico fijo para el emparejamiento Bluetooth (ej. "914257").

Roles disponibles:

Rol	Valor
Client (por defecto)	meshtastic_Config_DeviceConfig_Role_CLIENT
Client Mute	meshtastic_Config_DeviceConfig_Role_CLIENT_MUTE
Client Hidden	meshtastic_Config_DeviceConfig_Role_CLIENT_HIDDEN
Tracker	meshtastic_Config_DeviceConfig_Role_TRACKER
Sensor	meshtastic_Config_DeviceConfig_Role_SENSOR
TAK	meshtastic_Config_DeviceConfig_Role_TAK
TAK Tracker	meshtastic_Config_DeviceConfig_Role_TAK_TRACKER

LoRa y región

Parámetro	Descripción
USERPREFS_CONFIG_LORA_REGION	Banda de frecuencia de tu país/región.
USERPREFS_LORACONFIG_MODEM_PRESET	Preset de velocidad/alcance de radio (ver tabla de presets abajo).
USERPREFS_LORACONFIG_CHANNEL_NUM	Slot de canal dentro de la banda (0 = autoselección basada en el nombre).
USERPREFS_CONFIG_LORA_IGNORE_MQTT	true para ignorar completamente los paquetes provenientes de MQTT.
USERPREFS_LORA_TX_DISABLED	1 para desactivar la transmisión LoRa (modo solo recepción).

Presets de módem disponibles:

Preset	Valor
Long Fast (por defecto)	meshtastic_Config_LoRaConfig_ModemPreset_LONG_FAST
Long Moderate	meshtastic_Config_LoRaConfig_ModemPreset_LONG_MODERATE
Long Turbo	meshtastic_Config_LoRaConfig_ModemPreset_LONG_TURBO
Medium Fast	meshtastic_Config_LoRaConfig_ModemPreset_MEDIUM_FAST
Medium Slow	meshtastic_Config_LoRaConfig_ModemPreset_MEDIUM_SLOW
Short Fast	meshtastic_Config_LoRaConfig_ModemPreset_SHORT_FAST
Short Slow	meshtastic_Config_LoRaConfig_ModemPreset_SHORT_SLOW
Short Turbo	meshtastic_Config_LoRaConfig_ModemPreset_SHORT_TURBO
Lite Fast (EU 866MHz)	meshtastic_Config_LoRaConfig_ModemPreset_LITE_FAST
Lite Slow (EU 866MHz)	meshtastic_Config_LoRaConfig_ModemPreset_LITE_SLOW
Narrow Fast (EU 868MHz)	meshtastic_Config_LoRaConfig_ModemPreset_NARROW_FAST
Narrow Slow (EU 868MHz)	meshtastic_Config_LoRaConfig_ModemPreset_NARROW_SLOW

Códigos de región para España:

Región	Valor
Europa 868MHz	meshtastic_Config_LoRaConfig_RegionCode_EU_868
Europa 433MHz	meshtastic_Config_LoRaConfig_RegionCode_EU_433

Canales

Se pueden preconfigurar hasta 3 canales (índices 0, 1 y 2).

Parámetro	Descripción
USERPREFS_CHANNELS_TO_WRITE	Número de canales a inicializar en el arranque (1 a 3).
USERPREFS_CHANNEL_0_NAME	Nombre del canal (máx. 11 caracteres). Disponible también para _1_ y _2_.
USERPREFS_CHANNEL_0_PSK	Clave precompartida. Usa { 0x01 } para la clave pública por defecto, o un array de 32 bytes hexadecimales para un canal privado.
USERPREFS_CHANNEL_0_PRECISION	Precisión de ubicación para el canal (ej. 14 = alta, valores bajos = menor precisión).
USERPREFS_CHANNEL_0_UPLINK_ENABLED	true o false — si el canal sube mensajes a MQTT.
USERPREFS_CHANNEL_0_DOWNLINK_ENABLED	true o false — si el canal descarga mensajes de MQTT.

Posición GPS fija

Ideal para nodos estáticos (repetidores, nodos solares) que no tienen módulo GPS.

Parámetro	Descripción
USERPREFS_FIXED_GPS	true para activar la posición fija.
USERPREFS_FIXED_GPS_LAT	Latitud en formato decimal (ej. "40.284297").
USERPREFS_FIXED_GPS_LON	Longitud en formato decimal (ej. "-3.927447").
USERPREFS_FIXED_GPS_ALT	Altitud en metros (ej. "650"). Opcional.

aviso

Las coordenadas GPS fijas solo se aplican durante el primer arranque o justo después de un restablecimiento de fábrica. Si el dispositivo ya ha arrancado antes, no sobreescribirá las coordenadas almacenadas.

Administración remota

Se pueden preconfigurar hasta 3 claves públicas de administración remota. Cuando otro nodo envíe un comando administrativo firmado con la clave privada correspondiente, este nodo lo aceptará. Tienes más contexto en la guía de administración remota.

Parámetro	Descripción
USERPREFS_USE_ADMIN_KEY_0	Clave pública principal del administrador (array de 32 bytes hexadecimales).
USERPREFS_USE_ADMIN_KEY_1	Clave pública secundaria.
USERPREFS_USE_ADMIN_KEY_2	Clave pública terciaria.

tip

La clave que debes poner aquí es la clave pública (public key) de tu nodo administrador personal, formateada en hexadecimal byte a byte. Nunca introduzcas una clave privada.

Intervalos de posición y telemetría

Parámetro	Descripción
USERPREFS_CONFIG_POSITION_BROADCAST_INTERVAL	Cada cuántos segundos se emite la posición (ej. 86400 = una vez al día).
USERPREFS_CONFIG_GPS_UPDATE_INTERVAL	Cada cuántos segundos se consulta el módulo GPS.
USERPREFS_CONFIG_SMART_POSITION_ENABLED	true o false — emite posición solo cuando el nodo se ha movido.
USERPREFS_CONFIG_GPS_MODE	Modo del GPS. Usa meshtastic_Config_PositionConfig_GpsMode_DISABLED para apagarlo.
USERPREFS_CONFIG_DEVICE_TELEM_UPDATE_INTERVAL	Intervalo de telemetría del dispositivo, en segundos.
USERPREFS_CONFIG_ENV_TELEM_UPDATE_INTERVAL	Intervalo de telemetría ambiental (sensores), en segundos.
USERPREFS_CONFIG_ENVIRONMENT_MEASUREMENT_ENABLED	1 para forzar lecturas de sensores (BMP280, etc.) y emisión por LoRa desde el primer arranque.

MQTT

Parámetro	Descripción
USERPREFS_MQTT_ENABLED	1 para activar el módulo MQTT.
USERPREFS_MQTT_ADDRESS	Dirección del broker (ej. "'mqtt.meshtastic.es'"). Ojo con las comillas simples adicionales.
USERPREFS_MQTT_USERNAME	Usuario MQTT.
USERPREFS_MQTT_PASSWORD	Contraseña MQTT.
USERPREFS_MQTT_ENCRYPTION_ENABLED	true para cifrar los paquetes enviados por MQTT.
USERPREFS_MQTT_TLS_ENABLED	true o false para habilitar TLS.
USERPREFS_MQTT_ROOT_TOPIC	Tema raíz personalizado (ej. "event/mi-evento").

WiFi (solo ESP32)

Parámetro	Descripción
USERPREFS_NETWORK_WIFI_ENABLED	true para activar WiFi en el arranque.
USERPREFS_NETWORK_WIFI_SSID	Nombre de la red WiFi.
USERPREFS_NETWORK_WIFI_PSK	Contraseña WiFi.
USERPREFS_NETWORK_ENABLED_PROTOCOLS	1 para habilitar UDP mesh por red.
USERPREFS_NETWORK_IPV6_ENABLED	1 para habilitar IPv6.

Branding OEM (pantalla de inicio personalizada)

Puedes sustituir el logo y texto de arranque de Meshtastic por uno personalizado de tu comunidad o grupo.

Parámetro	Descripción
USERPREFS_OEM_TEXT	Texto personalizado en la pantalla de arranque (ej. "Meshtastic España").
USERPREFS_OEM_FONT_SIZE	Tamaño de fuente (0 = pequeño, 1 = mediano, 2 = grande).
USERPREFS_OEM_IMAGE_WIDTH	Ancho del logo personalizado, en píxeles.
USERPREFS_OEM_IMAGE_HEIGHT	Alto del logo personalizado, en píxeles.
USERPREFS_OEM_IMAGE_DATA	Datos de imagen como array de bytes XBM (ej. { 0x00, 0xFF, ... }).

Notificaciones y zona horaria

Parámetro	Descripción
USERPREFS_RINGTONE_RTTTL	Tono de notificación personalizado en formato RTTTL.
USERPREFS_RINGTONE_NAG_SECS	Segundos antes de repetir la notificación de mensaje no leído (ej. 60).
USERPREFS_TZ_STRING	Zona horaria en formato POSIX. Para España peninsular: "CET-1CEST,M3.5.0,M10.5.0/3". Para Canarias: "WET0WEST,M3.5.0/1,M10.5.0".

Modo evento

Configuraciones especiales para eventos con muchos nodos.

Parámetro	Descripción
USERPREFS_EVENT_MODE	1 para activar el modo evento. Aplica restricciones estrictas: limita saltos a 2, aumenta retardos, bloquea puertos no esenciales, degrada roles Router a Client, limita posición a 1 emisión cada 5 min y bloquea MQTT público.
USERPREFS_FIRMWARE_EDITION	Etiqueta la edición del firmware para que las apps (iOS/Android) muestren temas específicos del evento.