Manual de hamrlog

Qué es hamrlog#

hamrlog es un diario de contactos (un log) para radioaficionados que funciona en modo texto, dentro de una consola. La misma aplicación funciona en Linux, en PowerShell y en Windows Terminal, sin configurar nada distinto en cada sistema.

Está pensada para lo que pasa de verdad durante una sesión de radio. Configuras una sola vez la banda, la frecuencia, el modo y el equipo, y a partir de ahí solo escribes el indicativo y pulsas Enter. La fecha y la hora UTC, el informe por defecto, la emisora y la antena se ponen solos.

Todo ocurre en una única pantalla y con el teclado. No hay menús ni ventanas que abrir ni ratón que buscar: las teclas F1 a F9 cambian lo que muestra el recuadro central (el registro, el inventario, la agenda…) y la línea de entrada de abajo sirve para todo.

Lo que hace:

• Registra QSO con un indicativo y Enter, con avisos de duplicado y de indicativo mal escrito.
• Lleva el inventario de emisoras, antenas y fuentes, con un catálogo de lo que venden las tiendas españolas, y los equipos que montas con ellas.
• Guarda una agenda de contactos que se llena sola con lo que trabajas e importa listas de usuarios DMR.
• Usa perfiles para cambiar de golpe de banda, frecuencia, modo, equipo y repetidor, con Ctrl y una cifra.
• Trae la lista de repetidores de la URE y registra los QSO por repetidor con sus dos frecuencias.
• Entiende los modos digitales (DMR, D-STAR, C4FM, M17, FT8…) y sus datos.
• Exporta e importa ADIF y CSV, y exporta la agenda al CPS de la radio.

hamrlog es software libre con licencia MIT. El código está en GitHub.

Instalación#

Windows#

Descarga hamrlog-X.Y.Z-setup.exe de la última versión y ejecútalo. No hace falta tener Python: va dentro del programa. El instalador añade hamrlog al menú Inicio y, si marcas la casilla, al PATH, para poder abrirlo desde cualquier consola escribiendo hamrlog.

Si prefieres no instalar nada, descarga hamrlog-windows-x86_64.exe y ejecútalo tal cual.

Usa Windows Terminal mejor que la consola clásica: los colores y los caracteres de dibujo se ven correctamente. La aplicación pone la consola en UTF-8 por su cuenta, así que los acentos salen bien también en la antigua.

Linux#

Ejecutable suelto, sin necesidad de Python:

curl -LO https://github.com/manuel-alcocer/hamrlog/releases/latest/download/hamrlog-linux-x86_64
chmod +x hamrlog-linux-x86_64
./hamrlog-linux-x86_64

Con Python 3.10 o superior, en un entorno aislado y con el comando en el PATH:

git clone https://github.com/manuel-alcocer/hamrlog
cd hamrlog
./install.sh

El script usa uv o pipx si los tienes y, si no, crea un entorno virtual. Para desinstalarlo: ./install.sh --uninstall.

Arch Linux, con el PKGBUILD del repositorio:

cd packaging/arch
makepkg -si

Con pipx, directamente desde el repositorio:

pipx install git+https://github.com/manuel-alcocer/hamrlog

Desde el código#

git clone https://github.com/manuel-alcocer/hamrlog
cd hamrlog
python3 -m venv .venv
source .venv/bin/activate     # en Windows: .venv\Scripts\Activate.ps1
pip install -e .
hamrlog

Los extras opcionales añaden el exportador de Prometheus (.[metrics]) y la API REST (.[api]). Los ejecutables de las versiones publicadas no los incluyen: si los quieres, instala con pip.

Probarlo con la demo#

Antes de meter tus datos puedes probarlo todo con la demo:

hamrlog --demo --lang=es      # o, más corto: hamrlog -d -l es

Abre un diario de ejemplo: un operador (EA0ABC), cuatro equipos montados con el catálogo, cinco perfiles, unos sesenta contactos en la agenda y 160 QSO en HF, repetidores de FM y DMR. Todo es inventado: indicativos, nombres y QSO.

En la demo no se guarda nada. Puedes registrar, editar, borrar o cambiar la configuración; al salir se descarta, y la siguiente demo empieza con los mismos datos. La línea superior lo recuerda con la marca DEMO.

Todas las capturas y los vídeos de este manual son de la demo.

Primer arranque#

hamrlog

La primera vez que se abre, hamrlog pide un operador, porque sin él no se puede registrar ningún contacto:

Con eso ya puedes registrar. Lo siguiente que conviene hacer, en este orden:

1. Montar tus equipos en el inventario (F2), para que cada QSO guarde la emisora y la antena que usaste.
2. Crear un perfil por cada forma habitual de trabajar (40 m en SSB desde casa, el repetidor de la zona, FT8 en 20 m…) en Perfiles (F4), y marcar como predeterminado el que uses más.
3. Si haces DMR, importar la lista de usuarios en la agenda.

La pantalla#

Todas las vistas tienen la misma forma, de arriba abajo:

1. Línea superior: con qué se va a registrar el próximo QSO. Operador, banda, frecuencia (QRG), modo, equipo y perfil activo; si sales por un repetidor, también el repetidor (VÍA) y los datos digitales.
2. Ventana principal: la lista de lo que estés viendo. En el Registro, los QSO, con una línea discontinua entre días distintos (UTC). La última fila es siempre <Insertar nuevo> (o <Nuevo contacto>, <Nuevo perfil>… en las demás vistas).
3. Detalle: todo lo que no cabe en una fila de lo que esté señalado. Sobre <Insertar nuevo>, lo que heredará el próximo QSO, para que lo veas antes de pulsar Enter.
4. Entrada: las casillas donde se escribe. Las respuestas de la aplicación (QSO guardado, errores, avisos de duplicado) salen en el borde inferior de este recuadro.
5. Línea de estado: la hora UTC (y la local, si la configuras), el total de QSO, los de hoy, los indicativos únicos y los países, y las teclas de función de cada vista.

El teclado no sale nunca de la línea de entrada: no hay Tab hacia otros paneles. Escribes, y las flechas recorren la lista de arriba.

Cada tecla lleva a su vista desde cualquier otra. F1 es siempre el registro.

Registrar un QSO#

En el registro, la línea de entrada tiene una casilla por campo:

 IND  EA4ABC       NOMBRE  Juan          ENV  59   REC  57   QTH  Madrid       NOTAS

Solo el indicativo es obligatorio. Con escribirlo y pulsar Enter el QSO queda registrado con:

• la fecha y la hora UTC del momento en que pulsas Enter;
• la banda, la frecuencia, el modo, el equipo y el repetidor de la línea superior;
• el informe por defecto del modo: 59 en fonía, 599 en CW, −10 en FT8;
• la emisora y la antena del equipo que cubran esa frecuencia;
• el nombre y el QTH de la agenda, si la estación está en ella.

Lo que escribas en una casilla siempre manda sobre lo que pondría la aplicación. Las comas no separan nada: son texto corriente, así que una nota puede llevarlas.

Mientras escribes el indicativo, bajo la línea de entrada aparece:

• DUPLICADO, si ya está en el registro, con cuántas veces lo has trabajado y la fecha, banda y modo del último contacto;
• quién es, si está en la agenda (nombre, ciudad, ID DMR…).

Tras guardar, el cursor vuelve a <Insertar nuevo> y la línea de entrada se vacía para el siguiente.

Indicativos mal escritos#

Al teclear, el indicativo se contrasta con la forma que tiene uno real (prefijo, dígito y sufijo). Si no encaja se avisa mientras escribes y al pulsar Enter no se guarda, diciendo qué falla: le falta el número, es demasiado corto, lleva caracteres que un indicativo no tiene…

Pasan sin problema los indicativos especiales y los portables (AM500ITU, 9A1AA, 3DA0RS, F/EA7WM/P). Para forzar uno inusual que el filtro no admita, termínalo en !: BV100!.

QSO automáticos y manuales#

Cada QSO lleva una marca que se ve en el detalle:

• AUTO: la fecha y la hora las puso el programa al pulsar Enter. Son la prueba de cuándo ocurrió el contacto, así que se puede corregir todo menos la fecha y la hora.
• MANUAL: QSO importados de un ADIF o con la fecha puesta a mano. No los cronometró la aplicación, así que todos sus campos son editables, fecha incluida.

Recorrer y corregir el registro#

↑ y ↓ recorren el registro; RePág y AvPág, de diez en diez. Las líneas discontinuas entre días se saltan solas. El detalle muestra todo lo del QSO señalado: locator, equipo, operador, informes, datos del modo digital, el comentario entero y las dos frecuencias si fue por un repetidor.

Sobre un QSO ya registrado la línea de entrada deja de aceptar texto y ofrece sus acciones en una franja:

 V ver · D suprimir · E editar · R repetir · Espacio marca · Ctrl+A todos · ↓ volver a escribir

Las letras no escriben mientras recorres el registro. D, E y R son letras corrientes en un indicativo, y una tecla que unas veces escribe y otras borra sería una trampa. Lo que tuvieras a medio escribir se guarda al subir y vuelve intacto al bajar. Enter con algo escrito guarda un QSO nuevo estés donde estés.

Editar#

E no abre ninguna ventana: la línea de entrada se rellena con el QSO y añade una segunda fila con frecuencia, modo y equipo. Cambias lo que haga falta, Enter guarda y Esc cancela. La banda no se escribe: se calcula a partir de la frecuencia.

Con más de un QSO marcado, E los edita todos a la vez, pero solo en frecuencia, modo y equipo. Cada casilla empieza con el valor que comparten, o vacía si difieren; una casilla vacía deja cada QSO como estaba.

Repetir guarda el QSO con la banda y el modo actuales, no con los de entonces: repetir es volver a trabajar a esa estación, no rearchivar el contacto viejo.

La columna INFO#

Lleva una letra por cada cosa que señalar, o nada:

Borrar#

• Ctrl+D desde la línea de entrada borra el último QSO registrado: el caso habitual de acabar de guardar un indicativo mal escrito. Sobre un QSO señalado, borra ese.
• D (o Supr) sobre un QSO lo borra.
• /borrar o /deshacer borran el último.

Todo borrado pregunta antes, con el indicativo, la fecha, la banda y el modo. Se responde con S (sí), N o Esc (no), o moviéndose con ← → o Tab entre los botones y confirmando con Enter. La pregunta empieza con No seleccionado, para que un Enter por inercia no se lleve nada por delante.

Comandos#

Los comandos se escriben en la primera casilla de la línea de entrada, empezando por /, y se ejecutan con Enter. Cambian lo que hereda el próximo QSO:

En la agenda y en los repetidores está además /buscar, y en el inventario /marca. Un comando escrito sin su valor (/banda) responde cómo se usa.

Cambiar a mano la banda, la frecuencia, el modo o el repetidor deja de usar el perfil activo (sus valores siguen hasta que los cambies). Cambiar de banda o de frecuencia te saca además del repetidor, porque deja de describir dónde trabajas.

Modos#

/modo acepta cualquiera, analógico o digital: SSB, CW, FM, AM, DMR, D-STAR, C4FM, M17, FT8, FT4, RTTY…

Al elegir uno digital se piden los datos que ese modo necesita, y se aplican a todos los QSO hasta que los cambies:

En ADIF se exportan con su equivalencia correcta: DMR, D-STAR y C4FM son MODE=DIGITALVOICE con el SUBMODE correspondiente, y los datos que no tienen campo estándar viajan como APP_HAMRLOG_TALKGROUP, APP_HAMRLOG_NETWORK, etc.

Inventario (F2)#

F2 convierte la ventana principal en el inventario, con cuatro pestañas. Funciona como el registro: la lista arriba, la línea de entrada abajo para escribir, ↑ ↓ para recorrerla y <Nuevo …> al final.

Cada emisora, antena y fuente recibe al darse de alta un ID automático y único: E0001 las emisoras, A0001 las antenas y S0001 las fuentes. Es la primera columna de la lista y no se escribe ni se cambia. Una emisora sin nombre se llama «marca modelo».

Montar un equipo#

En la pestaña Equipos, las casillas de emisoras, antenas y fuentes llevan sus ID o sus nombres, separados por comas (E0001, E0003 o Icom IC-705, Diamond X-300N). Mientras escribes, se sugiere el nombre que encaja, y → al final de la casilla lo completa.

Un equipo necesita al menos una emisora. Al registrar, cada QSO toma del equipo la emisora y la antena que cubren su frecuencia, que en ADIF salen como MY_RIG y MY_ANTENNA. Si ninguna emisora sintoniza esa frecuencia, o ninguna antena trabaja esa banda, el QSO se guarda igual, pero su columna INFO muestra E y el detalle explica por qué.

El catálogo#

El inventario viene con un catálogo de emisoras, antenas y fuentes a la venta en tiendas españolas. Sale atenuado: no se modifica ni se borra, solo se usa al montar equipos. Lo que des de alta tú, sí. Si tienes algo que no está en el catálogo, dalo de alta en su pestaña.

/marca yaesu filtra la lista por marca (vale el principio del nombre) y /marca sola quita el filtro. Alt+↑ y Alt+↓ recorren las marcas de la pestaña una a una.

Agenda (F3)#

La agenda guarda una ficha por indicativo. F3 la muestra en la ventana principal, como el inventario: la lista arriba, <Nuevo contacto> al final, E y D sobre una ficha. Como una ficha tiene muchos datos, la línea de entrada tiene aquí dos filas:

 IND  EA4ABC       NOMBRE  Juan          APELLIDOS  Pérez García    ID DMR  2141234  LOC  IN80
 CIUDAD  Madrid        PROVINCIA  Madrid        PAÍS  España        CORREO                NOTAS

El país se escribe en tu idioma. El detalle de cada ficha dice cuántos QSO tienes con esa estación, y la última columna de la lista también.

Una lista de usuarios DMR puede traer decenas de miles de fichas, así que la agenda enseña como mucho 500 a la vez. /buscar texto busca en indicativo, nombre, ciudad, provincia, país o ID DMR, y /buscar sola vuelve a todas. La cabecera dice cuántas hay y cuántas se ven; RePág y AvPág pasan página.

Se llena sola#

Al registrar un indicativo que no está en la agenda, se da de alta con el nombre, el QTH y el país del propio QSO. Las fichas que ya existen no se tocan —lo que escribiste ahí vale más que lo de un contacto suelto—, salvo lo que les falte: si no tienen nombre toman el que escribas al registrar, y si no tienen ciudad toman el QTH. Los portables (F/EA4ABC/P) se archivan bajo el indicativo de casa, así que no se duplican.

Importar un ADIF no da de alta contactos: solo lo hace lo que registras en directo, para que un fichero de miles de QSO no se convierta en miles de fichas a medias.

Importar listas de usuarios DMR#

Desde la línea de órdenes, con el formato detectado solo:

hamrlog contacts import ~/Descargas/user.csv
hamrlog contacts import ~/Descargas/user.csv --country Spain   # solo los de España

Se detecta el separador (,, ;, tabulador), se tolera texto que no esté en UTF-8 y se reconstruye el nombre cuando viene en una sola columna. Un fichero que no sea una lista de contactos se rechaza en vez de llenarte la agenda de basura.

Reimportar no duplica: reconoce al mismo operador por ID DMR o por indicativo, rellena lo que falte y nunca pisa un dato escrito a mano.

Exportar a la radio#

hamrlog contacts export contactos.csv --format anytone

En el formato de la radio se omiten los contactos sin ID DMR: la emisora no puede usarlos.

Perfiles (F4)#

Un perfil es lo que hereda cada QSO mientras está activo: operador, equipo, frecuencia (la banda sale de ella), modo, potencia, repetidor y datos del modo digital. Con un perfil activo basta con escribir el indicativo en el registro y pulsar Enter.

F4 muestra la lista con <Nuevo perfil> al final y dos filas de casillas:

 CTRL  1    NOMBRE  40m casa      OPERADOR  EA7WM       EQUIPO  Casa
 FREC  7.100        MODO  SSB     POT  100   REPETIDOR             DIGITAL

En la lista, ▶ señala el perfil activo y ★ el predeterminado. El perfil activo sale en la línea superior. Editarlo aplica los cambios a los QSO que vengan, no a los ya registrados.

/perfil nombre o /perfil 3 también lo activan; es útil en terminales que no distinguen Ctrl más una cifra.

Repetidores (F5)#

F5 lista los repetidores. Vienen cargados los publicados por la URE en 10 m, 6 m, 2 m, 70 cm y 23 cm. Como el catálogo del inventario, salen atenuados y no se modifican ni se borran; los que añadas tú, sí.

Cada uno lleva su número de la URE (R5, R73), indicativo, frecuencia de salida (la que escuchas) y de entrada (la que transmites), tono CTCSS, modo, canal IARU (RV58, RU698), locator y titular.

/buscar mira en indicativo, número URE, canal, titular, lugar, locator, banda y modo, y cada palabra acota más: /buscar R5, /buscar dmr madrid, /buscar IN80. /buscar sola vuelve a la lista entera.

Enter sobre un repetidor lo sintoniza, igual que /repetidor: se adopta todo lo que define (frecuencia de escucha y de transmisión, banda, modo y datos digitales) y puedes registrar en el acto. /directo vuelve a simplex.

Para dar de alta uno, escribe sobre <Nuevo repetidor>:

 IND  ED1YAB      SALIDA  145.725    ENTRADA  145.125   TONO  77.0   MODO  FM   URE  R5   CANAL  RV58
 TITULAR  Radio Club Rioja        QTH                     LOC  IN82PO   DIGITAL           NOTAS

Un mismo indicativo puede ser varios repetidores (un radioclub con uno D-STAR, otro DMR y otro C4FM). Se distinguen añadiendo la frecuencia de salida, el modo o la banda: /repetidor ED4ZAH DMR, /repetidor ED4ZAH 438.325. En la casilla REPETIDOR de un perfil, igual.

Un QSO por repetidor es un QSO en split, y así se exporta: FREQ lleva la frecuencia de entrada (lo que transmites), FREQ_RX la de salida (lo que escuchas) y PROP_MODE vale RPT, como define ADIF. El indicativo del repetidor viaja en APP_HAMRLOG_REPEATER y se conserva al reimportar.

Herramientas (F8)#

Utilidades de consulta, una por pestaña. De momento, el código Q. Lo que escribes en la casilla FILTRO acota la lista al momento (qsy, potencia, frecuencia), y ↑ ↓ la recorren sin salir de la casilla. El detalle muestra el código como afirmación y como pregunta.

Configuración (F9)#

Una fila por ajuste. Enter o E ponen su valor en la casilla VALOR, Enter lo guarda y Esc cancela.

Se guardan en config.json, en la carpeta de configuración (~/.config/hamrlog/ en Linux, %APPDATA%\hamrlog\ en Windows).

Idioma#

La interfaz está en español y en inglés. Se elige sola según el idioma del sistema, salvo que la fijes en la configuración. hamrlog --lang=es (o -l es) o la variable HAMRLOG_LANG=es la fuerzan por encima de todo.

Frecuencias y unidades#

Una frecuencia escrita sin unidad se entiende en megahercios: 7.130, 145.500. Con unidad, la unidad manda: 7130 k son kilohercios. Da igual cómo la escribas:

Los desplazamientos de repetidor sin unidad son siempre kilohercios (-600), porque así se escriben en las radios. La exportación ADIF usa siempre megahercios con punto decimal, que es lo que fija la norma.

Importar y exportar#

Desde la línea de órdenes:

hamrlog export log.adi                       # todo el registro en ADIF
hamrlog export --format csv log.csv          # o en CSV
hamrlog import otro.adi --operator EA7WM     # importa un ADIF

El ADIF exportado lleva la emisora y la antena de cada QSO (MY_RIG, MY_ANTENNA), los modos digitales con su SUBMODE, los QSO por repetidor en split y los datos propios de hamrlog en campos APP_HAMRLOG_…, que se recuperan al reimportar. Los QSO importados quedan como MANUAL.

Las órdenes de la agenda están en Agenda. Todas las órdenes:

hamrlog                                      # abre la interfaz
hamrlog -l en                                # en inglés, solo esta vez
hamrlog --demo -l es                         # la demo, en español
hamrlog info                                 # rutas, base de datos y versión
hamrlog export log.adi                       # exporta el registro a ADIF
hamrlog export --format csv log.csv          # exporta a CSV
hamrlog import otro.adi --operator EA7WM     # importa un ADIF
hamrlog contacts import user.csv             # importa una lista de usuarios DMR
hamrlog contacts export c.csv --format anytone   # contactos para el CPS de la radio
hamrlog contacts list ea7                    # busca en la agenda
hamrlog metrics --port 9119                  # solo el exportador de Prometheus
hamrlog build-demo                           # rehace la base de datos de la demo

Dónde se guardan los datos#

En una base de datos SQLite, en la carpeta estándar de cada sistema:

hamrlog info dice cuál está usando. Para hacer una copia de seguridad basta con copiar ese fichero con la aplicación cerrada.

Dos variables de entorno lo cambian:

export HAMRLOG_HOME=/ruta/a/mis/datos
export HAMRLOG_DATABASE_URL=postgresql+psycopg://usuario:clave@servidor/hamrlog

La segunda permite usar PostgreSQL, que es lo que necesitas para compartir el registro entre varios ordenadores. El fichero también se elige en la configuración; la variable, si está, manda.

Varios operadores pueden compartir la misma base de datos: cada QSO queda asociado a quien lo registró. No hay contraseñas. El operador se cambia con un perfil.

Integraciones#

Prometheus#

hamrlog metrics arranca un exportador para Prometheus (hace falta instalar con el extra metrics). Publica en /metrics:

hamrlog_qso_total, hamrlog_qso_today, hamrlog_unique_callsigns_total,
hamrlog_countries_total, hamrlog_qso_by_band{band}, hamrlog_qso_by_mode{mode}

Las métricas se calculan en cada consulta, así que son correctas aunque reinicies o edites QSO desde fuera.

API REST#

pip install "hamrlog[api] @ git+https://github.com/manuel-alcocer/hamrlog"
uvicorn hamrlog.api.server:app

Expone /health, /operators, /qsos, /qsos/{id} y /stats. Es de solo lectura a propósito: abrir la escritura exige decidir cómo autenticar, y esa decisión corresponde a quien la despliegue.

Todas las teclas#

En cualquier vista

Escribiendo en el registro

Sobre un QSO, un contacto, un elemento, un perfil o un repetidor

En el inventario

En una confirmación

Problemas frecuentes#

Los recuadros o los acentos se ven mal en Windows. Usa Windows Terminal en lugar de la consola clásica.

Ctrl más una cifra no hace nada. Algunos terminales no distinguen esas combinaciones. Activa el perfil con /perfil 3 o /perfil nombre, o con Enter sobre él en F4.

Un indicativo no se guarda. No tiene la forma de uno real; el mensaje del borde de la entrada dice qué falla. Si es correcto pero inusual, termínalo en !.

Un QSO sale con E en la columna INFO. Ninguna emisora del equipo sintoniza esa frecuencia, o ninguna antena trabaja esa banda. Revisa el equipo en el inventario o elige otro.

No puedo cambiar la fecha de un QSO. Es un QSO AUTO: la hora la puso el programa y es la prueba del contacto.

¿Dónde está mi base de datos? hamrlog info lo dice.

Algo no funciona como dice este manual. Abre una incidencia en GitHub.