Milesight WS301: LoRaWAN Door/Window Contact Sensor

Milesight WS301 LoRaWAN door/window contact sensor: own ChirpStack/ThingsBoard decoder, decoded example, tamper alarm and access monitoring integration.

Milesight WS301
WS301Sensor
LoRaWAN
Class A, OTAA, default port 85
Bands
EU868 / US915 / AS923 and more
Detection
Magnetic reed contact, triggers within roughly 2 cm
Tamper
Built-in install / dismount detection
Battery
1200 mAh ER14250, up to ~6.8 years (SF7)
Ingress protection
IP20, indoor / dry-area use
Configuration
NFC (Milesight ToolBox)
Measurements

What the WS301 measures

Door / window state

Open or close, reported on every state change.

Tamper status

Install / uninstall detection alerts when the device is dismounted.

Battery level

Percentage, reported periodically alongside the state heartbeat.

Data into your dashboard

Integration

Sensor / controller

Measures or controls in the field and sends LoRaWAN uplinks.

LoRaWAN gateway

Receives the radio packets and forwards them to the server.

ChirpStack

Network server: manages sessions and decodes the payload.

ThingsBoard / Grafana

Dashboards, alarms, rules and reports.

ChirpStack v4 · decodeUplink
function decodeUplink(input) {
  var bytes = input.bytes;
  var data = {};

  for (var i = 0; i < bytes.length; ) {
    var channel = bytes[i++];
    var type = bytes[i++];

    if (channel === 0x01 && type === 0x75) {          // battery (%)
      data.battery = bytes[i]; i += 1;
    } else if (channel === 0x03 && type === 0x00) {   // door / window state
      data.magnet_status = bytes[i] === 0 ? "close" : "open"; i += 1;
    } else if (channel === 0x04 && type === 0x00) {   // install / tamper state
      data.tamper_status = bytes[i] === 0 ? "installed" : "uninstalled"; i += 1;
    } else if (channel === 0xff) {                     // device info (join / power-on)
      i += deviceInfoLen(type);
    } else {
      break;
    }
  }
  return { data: data };
}

function deviceInfoLen(type) {
  // 0xFF channels carry version/SN/status fields of fixed length
  if (type === 0x01 || type === 0x0f || type === 0x0b || type === 0xfe) return 1; // ipso ver, class, status, reset
  if (type === 0x09 || type === 0x0a || type === 0xff) return 2;                  // hw, fw, tsl version
  if (type === 0x08) return 6;                                                    // serial number
  return 1;
}

Implemented from the published Milesight byte specification (Communication Protocol / User Guide).

Channel format: 01 75 battery (UINT8, %), 03 00 door/window state (0 close, 1 open), 04 00 install/tamper state (0 installed, 1 uninstalled). 0xFF channels carry device info on join and power-on. Implemented from the published Milesight byte specification. For ThingsBoard the same channel logic goes into an uplink converter.

Uplink (hex)

017564030001040001

Decoded JSON

{ "battery": 100, "magnet_status": "open", "tamper_status": "uninstalled" }
From the field

Configuration & pitfalls

NFC setup

Keys, reporting interval and tamper behaviour are set over NFC with the Milesight ToolBox before rollout.

Event vs heartbeat

State changes are sent immediately; a periodic heartbeat confirms the device is alive. Dashboard rules should treat the change event as the primary trigger.

Magnet alignment

The reed switch triggers within roughly 2 cm of the magnet. Mount both halves flush and within range, or the contact reports open when the door is shut.

Tamper handling

Install detection fires an uplink when the body is removed from its base. Map tamper_status uninstalled to a security alarm, not just a log entry.

Your partner

How merkaio supports your WS301

From sourcing to day-to-day operation, all from one partner on our own European infrastructure.

Pre-staging & provisioning

We configure the WS301, set keys, intervals and alarms, and ship it ready to deploy.

Own decoder

Payload codec for ChirpStack v4 and ThingsBoard, implemented from the Milesight specification.

Dashboard integration

Data lands in your ThingsBoard or Grafana, with alarms and reports.

Operations & monitoring

We run the LoRaWAN stack and dashboards on European infrastructure, you just use the data.

Frequently asked questions

Yes. It is a standard LoRaWAN device, no Milesight gateway or cloud required. You add the codec to the device profile and provision it via OTAA.
Yes, for both ChirpStack and ThingsBoard, implemented from the published Milesight byte specification. The same channel logic goes into a ThingsBoard uplink converter.
It is a Class A device on LoRaWAN port 85. Each state change uplink carries the door/window status, and the battery level is reported periodically.
A magnetic reed contact that reports open or close, plus a tamper status that flags when the device is dismounted from its mounting base.
It runs on a replaceable 1200 mAh ER14250 cell. Milesight rates it at around 6.8 years at SF7 and about 4.2 years at SF10 on EU868, based on a long reporting interval plus roughly 30 triggers a day, so real life depends on data rate and how often the door moves.
Yes. State changes are sent immediately as an event uplink, outside the periodic heartbeat, so dashboard rules should treat the state change as a priority trigger.
No. The WS301 is rated IP20, which means it has no protection against water or dust ingress. Mount it indoors on dry door and window frames; for outdoor gates or wet rooms choose a sealed sensor instead.
As a Class A device it only listens in the two receive windows right after an uplink, so a downlink such as a reporting-interval change is queued in ChirpStack and delivered on the next uplink, not instantly.
From the same series

Related devices

Let's discuss your infrastructure. Digital and on-site.

Whether it's IoT platform development, hardware selection, managed hosting for ChirpStack, ThingsBoard, Grafana or NetBird VPN, or migration from a self-hosted setup - we'll find the right solution for your use case. Book a free 30-minute consultation, no commitment required.

Timo Wevelsiep

Your contact

Timo Wevelsiep

Founder, merkaio

15 minutes, no commitment, directly with Timo.

By submitting, you agree to our Privacy Policy.

Decoder for ChirpStack v4. merkaio is an independent integrator and is not affiliated with Milesight.