Ir al contenido principal

Configurar Myriota: FlexSense y AssetHawk a la nube por HTTP

Envía datos de Myriota FlexSense y AssetHawk a Ubidots con un destino HTTP. Sin decodificador ni dispositivos que crear: llegan con unidades y ubicación.

Escrito por Sergio M

Ubidots recibe los mensajes de Myriota FlexSense y AssetHawk a través de un destino HTTP en Myriota Device Manager. Asigna el destino a tus dispositivos y cada uno aparece en Ubidots con su primer mensaje, ya decodificado: variables con nombre, unidades, su posición en el mapa y la hora en que el dispositivo tomó cada lectura.


​

Página de un dispositivo Myriota en Ubidots, con sus variables y su posición en el mapa, sobre una foto de un FlexSense instalado en campo


​

Tú, en Myriota Device Manager

Ubidots, con el primer mensaje

Creas un destino HTTP con la URL de Ubidots

Crea un dispositivo por cada Terminal ID de Myriota

Asignas el destino a tus dispositivos

Decodifica el payload: presets de firmware de FlexSense o tu propio struct, y los mensajes de ubicación y Bluetooth de AssetHawk


​

Nombra las variables conocidas, les asigna unidad e ícono, y fija la ubicación del dispositivo


​

Guarda cada valor en la hora de lectura del dispositivo, así los mensajes tardíos quedan en su lugar

En Ubidots no hay nada que crear: ni dispositivos, ni decodificador, ni mapeo de Terminal IDs.


​

Requisitos

  • Dispositivos Myriota FlexSense o AssetHawk registrados en Myriota Device Manager.

  • Un usuario de Device Manager que pueda crear destinos y editar dispositivos.

  • Una cuenta de Ubidots en industrial.ubidots.com, con cupo en tu plan para un dispositivo de Ubidots por cada dispositivo de Myriota, y tu token de Ubidots. ¿Aún no tienes cuenta? Empieza una prueba gratis.


​

Cómo llegan los datos a Ubidots

AssetHawk y FlexSense llegan a Myriota Cloud por satélite o celular. Myriota Cloud decodifica a JSON los mensajes de AssetHawk y envía los de FlexSense como bytes crudos, por HTTPS POST, a myriota.ubidots.com: /assethawk lee el JSON y /flexsense decodifica los bytes según el firmware de la URL. Luego cada uno llega a tu cuenta de Ubidots con tu token, como un dispositivo AssetHawk con 9 variables, incluida su posición, o un dispositivo FlexSense con las variables de su firmware. myriota.ubidots.com no guarda tu token.


​

Dispositivo

Ruta

Payload que recibe Ubidots

AssetHawk

/assethawk

JSON, ya decodificado por Myriota

FlexSense

/flexsense

Bytes crudos; la URL define el formato

myriota.ubidots.com no guarda copia de tu token: cada entrega lo lleva, y los datos solo van a la cuenta dueña del token. Usa de preferencia un token exclusivo para Myriota, así revocarlo no afecta nada más.

Pruébalo en un minuto, sin dispositivo

Esto envía un mensaje de ubicación de AssetHawk de ejemplo directo a Ubidots, como lo haría Myriota. Reemplaza YOUR_UBIDOTS_TOKEN y ejecútalo en una terminal:

NOW=$(date +%s)
cat > assethawk-test.json <<EOF
{"Data": "{\"Packets\":[{\"TerminalId\":\"test-assethawk\",\"SerialNumber\":\"TEST\",\"Timestamp\":${NOW}000,\"Value\":[{\"type\":1,\"sequence_number\":1,\"reason\":0,\"flags\":0,\"time\":${NOW},\"latitude\":-34.9285,\"longitude\":138.6007,\"elevation\":48,\"temperature\":23.5,\"battery_voltage\":3.6}]}]}"}
EOF
curl -s -X POST 'https://myriota.ubidots.com/assethawk?token=YOUR_UBIDOTS_TOKEN' --data @assethawk-test.json

La respuesta muestra "forwarded":1, y AssetHawk TEST aparece en Devices → Devices con nueve variables, incluida su posición. Bórralo cuando termines.


​

1. Arma la URL del destino

AssetHawk

Rastreador de activos Myriota AssetHawk

https://myriota.ubidots.com/assethawk?token=YOUR_UBIDOTS_TOKEN

No hay nada más que configurar. Myriota decodifica los mensajes de AssetHawk antes de entregarlos.

FlexSense

Myriota FlexSense con su cable de sensor

Un mensaje de FlexSense es un struct empaquetado cuyo formato depende del firmware del dispositivo, así que la URL indica el firmware. Los presets corresponden a las apps de referencia v1.6.0 de Myriota.

Firmware del dispositivo

App de referencia de Myriota

Agrega a la URL

Tracker (de fábrica)

001_tracker

nada

Sensor 4-20mA

002_sensor_4-20ma

&firmware=4-20ma

Contador de pulsos

003_pulse_counter

&firmware=pulse-counter

Tu propio firmware

—

&fields=… (ver Firmware propio de FlexSense)

https://myriota.ubidots.com/flexsense?token=YOUR_UBIDOTS_TOKEN&firmware=4-20ma

Un firmware equivocado decodifica sin dar error. Myriota rellena los mensajes hasta 20 bytes, así que cualquier formato los lee. Por ejemplo, un mensaje de Tracker leído como Pulse Counter convierte 23.45 °C en un conteo de 2345 pulsos.


​

Cada destino tiene una sola URL, así que los dispositivos con firmware distinto necesitan destinos separados, por ejemplo Ubidots Tracker y Ubidots 4-20mA.


​

2. Crea el destino HTTP

  1. En Myriota Device Manager, selecciona Destinations en el menú de la izquierda y haz clic en + Create.

  2. En New Destination, pon en Label un nombre como Ubidots, en Type elige HTTP y en URL pega la URL del paso 1.

  3. Haz clic en Create.

Ventana New Destination de Myriota Device Manager con Label Ubidots, Type HTTP y la URL de Ubidots para AssetHawk


​

3. Asigna el destino a cada dispositivo

Un destino no recibe nada hasta que lo asignas a un dispositivo. Crearlo no basta. Es la causa más común de que no lleguen datos a Ubidots.


​

  1. Selecciona Devices y abre el dispositivo.

  2. Haz clic en el + junto a Destination/s y luego en + Add Destination.

  3. Selecciona el destino que creaste en el paso 2.

Repite para cada dispositivo. Un dispositivo puede tener varios destinos y cada uno recibe todos los mensajes, así que tu plataforma actual sigue recibiendo datos mientras pruebas Ubidots.

Asigna una flota con la Cloud API de Myriota

El endpoint de asignación recibe un dispositivo por llamada, así que recorre los IDs en un ciclo: Module ID para FlexSense, ICCID para AssetHawk. El ID del destino está en la columna Id de Destinations. Para el token de la API, selecciona Tokens en Device Manager y haz clic en Create; consulta la guía Cloud APIs de Myriota.

DEST=YOUR_DESTINATION_ID
MYRIOTA_TOKEN=YOUR_MYRIOTA_API_TOKEN
for id in 89883380001234567890 89883380001234567891; do
curl -s -X POST "https://api.myriota.com/v1/destinations/$DEST/modules" \
-H "Authorization: $MYRIOTA_TOKEN" -H "Content-Type: application/json" \
-d "{\"Items\":[{\"Id\":\"$id\"}]}"
done

Cada respuesta lista el Id del dispositivo, con un ErrorMessage si esa asignación falló.


​

4. Revisa los datos en Ubidots

Ve a Devices → Devices. El dispositivo aparece con su primer mensaje, que llega en su siguiente reporte programado más el tiempo de entrega satelital. El firmware de fábrica de FlexSense reporta cuatro veces al día.

Lista de dispositivos de Ubidots con el AssetHawk creado automáticamente y su SIM ICCID como API label


​


​

FlexSense

AssetHawk

Identificador de Myriota (Terminal ID)

Module ID

SIM ICCID, no el número de serie de la etiqueta

API label del dispositivo en Ubidots

Module ID, en minúsculas

ICCID

Nombre del dispositivo en Ubidots

FlexSense <Module ID>

AssetHawk <Serial Number>

Si ya existe en Ubidots un dispositivo con ese API label, los datos llegan a ese dispositivo.


​

Abre el dispositivo para ver sus variables, sus unidades y su posición.

Dispositivo AssetHawk creado en Ubidots por su primer mensaje, con su posición en el mapa y nueve variables con nombre


​

Prueba un destino FlexSense desde Device Manager

  1. En Device Manager, selecciona Devices y haz clic en el ícono Test Destinations de un FlexSense asignado al destino.

  2. Escribe el mensaje de prueba de su firmware y haz clic en OK.

Firmware

Mensaje de prueba

Lo que debes ver en Ubidots

Tracker

010000000000000000000000002909100e

Temperature 23.45 °C, Battery Voltage 3.6 V

4-20mA

010000000000000000000000002909e02e100e

Temperature 23.45 °C, Sensor Current 12 mA, Battery Voltage 3.6 V

Pulse Counter

010000000000000000000000002a00100e

Pulse Count 42, Battery Voltage 3.6 V

Todos ponen Sequence Number en 1 y quedan guardados a la hora en que Myriota los capturó. Ninguno trae posición, así que el dispositivo no se mueve en el mapa. Si el dispositivo tiene otros destinos, también reciben la prueba. Para repetir una prueba, cambia los dos primeros caracteres, por ejemplo a 02.

AssetHawk

La prueba de Device Manager no puede producir un mensaje de AssetHawk: Myriota convierte datos arbitrarios en un error "unable to decode", que no agrega nada en Ubidots. Usa la prueba de un minuto de arriba o espera el siguiente reporte del dispositivo.


​

Variables

FlexSense

API label

Nombre

Unidad

Tracker

4-20mA

Pulse Counter

position

Position: fija la ubicación del dispositivo. Su valor siempre es 1; lat y lng van en su contexto

—

✓

✓

✓

temperature

Temperature, dentro del dispositivo

°C

✓

✓


​

battery_voltage

Battery Voltage

V

✓

✓

✓

sensor_current

Sensor Current

mA


​

✓


​

pulse_count

Pulse Count

—


​


​

✓

sequence_number

Sequence Number: contador de mensajes, de 0 a 255 y vuelve a empezar

—

✓

✓

✓

Mensajes de ubicación de AssetHawk

API label

Nombre

Unidad

Notas

position

Position

—

Fija la ubicación del dispositivo. No se escribe si el fix está desactualizado o es 0, 0

temperature

Temperature

°C


​

battery_voltage

Battery Voltage

V


​

elevation

Elevation

m


​

message_reason

Message Reason

—

Código de motivo del AssetHawk, de 0 a 7

tampered

Tampered

—

0 o 1, del bit 2 de flags

gps_stale

GPS Fix Stale

—

0 o 1, del bit 1 de flags: la posición repite el último fix conocido

bad_orientation

Bad Orientation

—

0 o 1, del bit 0 de flags

sequence_number

Sequence Number

—

Contador de los mensajes de ubicación

Los campos numéricos que un firmware más nuevo de AssetHawk agregue a los mensajes de ubicación pasan con su propio nombre.

Mensajes Bluetooth de AssetHawk

API label

Nombre

Unidad

Notas

ble_<mac>_rssi, por ejemplo ble_aabbccddeeff_rssi

Beacon AA:BB:CC:DD:EE:FF RSSI

dBm

Una variable por beacon. El contexto del valor guarda address, protocol, data (payload crudo del beacon) y sequence_number

Los reportes Bluetooth y los de ubicación son mensajes separados, cada uno con su propia marca de tiempo.


​

Cómo maneja Ubidots los datos

Situación

Qué pasa

Hora de la lectura

Ubidots usa la hora del propio dispositivo. Usa la hora de captura de Myriota si el reloj del dispositivo marca antes de 2020 o más de 24 horas adelante, si un firmware propio no tiene campo timestamp, y en los mensajes Bluetooth, cuya hora cuenta desde el arranque

Varias variables en un mensaje

Comparten la misma marca de tiempo, así que quedan alineadas en gráficas y exportaciones

Entrega tardía o fuera de orden

Cada valor queda guardado en su hora de lectura

Recepciones satelitales duplicadas

Myriota elimina las recepciones duplicadas de UltraLite antes de entregar

Varios mensajes en una entrega

Cada uno se procesa por separado, para uno o varios dispositivos

Sin fix GPS (0, 0)

No se escribe la posición; las demás variables sí

Relleno después del struct de FlexSense

Se ignora

Un mensaje que no se puede decodificar

Se descarta; el resto de la entrega se procesa

Control Messages (downlink)

No soportado: la integración es solo de subida


​

Firmware propio de FlexSense: fields=

El firmware de FlexSense envía su mensaje como un struct de C empaquetado. Agrega &fields= a la URL y lista los miembros del struct en orden como nombre:tipo, separados por comas.

Tipo

Tipo en C

Bytes

u8 / i8

uint8_t / int8_t

1

u16 / i16

uint16_t / int16_t

2

u32 / i32

uint32_t / int32_t

4

u64 / i64

uint64_t / int64_t

8

f32 / f64

float / double

4 / 8

  • Little-endian, como el FlexSense. Agrega be para big-endian, por ejemplo u16be.

  • /N divide y *N multiplica, por ejemplo level:u16/10. Escribe 1e7, no 1e+7: una URL convierte el + en un espacio.

  • Nombres reservados: timestamp (segundos Unix, se usa como hora de la lectura), lat y lng (grados; juntos fijan la posición del dispositivo) y _ (lee el miembro y lo descarta).

  • Cualquier otro nombre se vuelve una variable: letras minúsculas, números, _ y -, y cada nombre una sola vez. Los nombres de las tablas de variables, como temperature o battery_voltage, reciben su unidad e ícono automáticamente; configura los demás en Ubidots.

Un firmware que envía este struct:

struct {
uint8_t seq;
uint32_t time; // Unix seconds
int32_t lat; // degrees × 1e7
int32_t lng; // degrees × 1e7
uint16_t level_dm; // decimetres
} __attribute__((packed));

usa esta URL, que crea las variables seq y level (en metros) y fija la posición del dispositivo:

https://myriota.ubidots.com/flexsense?token=YOUR_UBIDOTS_TOKEN&fields=seq:u8,timestamp:u32,lat:i32/1e7,lng:i32/1e7,level:u16/10

Revisa un fields= antes de asignarlo

Envía una entrega vacía a la URL. No escribe nada en tu cuenta.

curl -s -X POST 'https://myriota.ubidots.com/flexsense?token=YOUR_UBIDOTS_TOKEN&fields=seq:u8,timestamp:u32,lat:i32/1e7,lng:i32/1e7,level:u16/10' \
-d '{"Data":"{\"Packets\":[]}"}'

Un formato válido responde 200 con {"firmware":"custom","received":0,…}. Uno inválido responde 400 con el motivo, por ejemplo Unknown type "u17" in "level:u17". Esta prueba no valida el token.


​

Token en un header en vez de la URL

El formulario de Device Manager solo recibe una URL, así que por defecto el token hace parte de la URL del destino que ve cualquier usuario de Device Manager. Para pasarlo a un header, configúralo con la Cloud API de Myriota y luego quita ?token= de la URL del destino.

PUT https://api.myriota.com/v1/destinations/YOUR_DESTINATION_ID/headers
Authorization: YOUR_MYRIOTA_API_TOKEN
Content-Type: application/json

{"X-Auth-Token": "YOUR_UBIDOTS_TOKEN"}
  • Un header X-Auth-Token tiene prioridad sobre ?token=, así que los datos siguen llegando mientras haces el cambio.

  • El header saca el token de la URL, no de la cuenta de Myriota: los usuarios de la API de esa cuenta todavía pueden leerlo.

  • Para cambiar de token, actualiza el header o la URL. La siguiente entrega usa el token nuevo.


​

Solución de problemas: ¿por qué no llegan datos a Ubidots?

Síntoma

Causa

Solución

No aparece el dispositivo en Ubidots

Destino sin asignar, aún no hay reporte o el token es incorrecto

Asígnalo (paso 3); espera el siguiente reporte programado; revisa el token de la URL, sin espacios

No aparece el dispositivo y el destino está asignado

Ruta equivocada (un FlexSense en /assethawk o un AssetHawk en /flexsense), o fields= describe más bytes de los que envía el dispositivo

Usa la ruta del dispositivo (paso 1); ajusta fields= para que coincida con el struct

Algunos dispositivos nunca aparecen

Tu plan de Ubidots llegó a su límite de dispositivos

Amplía el límite o borra dispositivos que no uses

Valores de FlexSense que no cuadran

El firmware de la URL no coincide con el del dispositivo, o a fields= le falta un miembro

Corrige firmware= (paso 1), o lista cada miembro del struct en orden y con su tipo

Un segundo dispositivo para el mismo AssetHawk

Cambió su SIM ICCID, por ejemplo tras un cambio de SIM; el número de serie no

Conserva el dispositivo anterior por su historial, o bórralo

El dispositivo no aparece en el mapa

Sin fix GPS (0, 0), o un fix desactualizado de AssetHawk

Los demás valores sí llegan. Dale al dispositivo vista despejada del cielo

Saltos en Sequence Number

Un mensaje se perdió o sigue en camino

Los mensajes tardíos quedan en su hora de lectura

Respuestas de myriota.ubidots.com

Código

Significado

200

Entrega procesada. El cuerpo cuenta los mensajes received, forwarded, duplicates, invalid y failed

400

firmware= o fields= inválido, o no es una entrega de Myriota. El cuerpo da el motivo

401

Falta el token, o Ubidots lo rechazó

502

Ubidots no pudo guardar un valor

Myriota reintenta toda respuesta distinta de 2xx, con esperas cada vez más largas entre intentos.


​

Preguntas frecuentes

¿Tengo que crear dispositivos o variables en Ubidots primero?

No. Cada dispositivo se crea con su primer mensaje, con sus variables. Si creaste antes un dispositivo con el mismo API label, el Terminal ID en minúsculas, ese dispositivo recibe los datos.

¿Puedo seguir enviando datos a mi plataforma actual?

Sí. Un dispositivo de Myriota puede tener varios destinos, y cada uno recibe todos los mensajes. Agrega el destino de Ubidots junto al que ya tienes.

¿Ubidots puede enviar Control Messages al dispositivo?

No. La integración es solo de subida. Envía Control Messages desde Myriota Device Manager o la Cloud API de Myriota.

¿Qué dispositivos de Myriota cubre?

FlexSense con el firmware de referencia Tracker, 4-20mA o Pulse Counter de Myriota, FlexSense con firmware propio descrito en fields=, y los mensajes de ubicación y Bluetooth de AssetHawk. Para otro dispositivo de Myriota, escríbenos por el chat.


​

Siguientes pasos

  • Alertas: Eventos sobre Battery Voltage, Tampered o GPS Fix Stale, un evento de inactividad para un dispositivo que deja de reportar, o una geocerca sobre su posición.

  • Mapas: un widget de mapa con la ubicación de toda la flota.

  • ¿Aún no tienes cuenta? Empieza una prueba gratis y ejecuta la prueba de un minuto de arriba.

¿Ha quedado contestada tu pregunta?