Skip to content

It's an IoT DIY project which notifies you when you have received a parcel or a letter in your letterbox. This project uses an HelTec AB01 LoRaWAN module to send data over an LoRaWAN Gateway when WiFi is out of range. I use an Helium Gateway from the People's Network in order to forward packets over Helium Network which send data to AWS IoT Core…

Notifications You must be signed in to change notification settings

vhuynen/CubeCell-AB01-LoRaWAN-Helium-Mailbox-Notifier

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

39 Commits
 
 
 
 
 
 

Repository files navigation

HelTec-Cube-LoRaWAN-Helium-Mailbox-Notifier

The Mailbox Notifier is an IoT DIY project which notifies you each time you received a package or a letter in your letterbox. This is the same projet as the ESP32-CAM-Mailbox-Notifier one, but designed for long range distance.

This project uses an HelTec AB01 LoRaWAN module to send data over an LoRaWAN Gateway when WiFi is out of range. I use an Helium Gateway from the People's Network in order to forward packets over Helium Network which sends data to AWS IoT Core (MQTT) or Pipedream (HTTP) etc... LoRaWAN is a bidirectional protocol useful when you need to send few data over long distance (several miles) from low-power and low-bandwidth IoT.

The compromise over this kind of system is that you can't send heavy payload as you are able to do over WiFi. Finally the data must be treated over third-part system.

Table of Contents

Architecture Schema

architecture

Helium Organization

Before going further, you should verify that you are within the coverage of the Helium Network. Your device should be at the proximity of a least one gateway (350 meters). If not, this allows you to expand the network with your own gateway. After that, you will have to create an account on the Helium Console.

Registering the device in the blockchain

You must register your device in the blockchain. This operation can take a while (20 mins) before your device can join the network. The registration generates three important values that you will have to report in the device's program later.

  • Device EUI :
    • The DevEUI is a 64-bit globally-unique Extended Unique Identifier (EUI-64) generated throught the Helium Console. This identifier is mandatory because the Helium router has an XOR filter that filters packets from devices it knows only.
  • App EUI :
    • the AppEUI is an application identifier, and this can be public without any concerns
  • App Key :
    • The App Key is an AES-128 secret key that is shared between the device and your Helium Organization. This Key is used to provide end-to-end symmetric encryption of your payload data.

Setting the AWS IoT Core Integration

Helium Console offers more than fifteen integrations and the list is constantly growing. As expected in the architecture the payload data is forwarded to your AWS Organization. You will have to connect your Helium Organization to your AWS Organization. In my case, the Uplink messages from Helium are published into a Topic named topic/gateway

Decoder Function

Function Decoder is a JavaScript function that allows you to decode the byte payload into a readable JSON Format. The decoded payload is added to the main JSON payload that is forwarded to your Integration target. The payload will be entirely formatted into a specific function that transcodes the mailbox's state (which is hexadecimal) into a readable message enriched by the battery voltage and battery level.

function Decoder(bytes, port, uplink_info) {

	//decode message type form payload
	var data = bytes[0];
	//output decoded message depending on the data
	switch (data) {
		case 0x03:
			return {
				msg: "Uplink n°" + uplink_info.fcnt + "\n[OK] You have got mail !\nBattery Voltage: "
					+ ((bytes[1] << 8) + bytes[2]) / 1000
					+ " Volts\nBattery Level: "
					+ ((((((bytes[1] << 8) + bytes[2]) / 1000) - 3.7) / (4.2 - 3.7)) * 100).toPrecision(4)
					+ "%\nHave a nice day !",
					code : 03
			};
		case 0x02:
			return {
				msg: "Uplink n°" + uplink_info.fcnt + "\n[OK] You have got maybe a package !\nBattery Voltage: "
					+ ((bytes[1] << 8) + bytes[2]) / 1000
					+ " Volts\nBattery Level: "
					+ ((((((bytes[1] << 8) + bytes[2]) / 1000) - 3.7) / (4.2 - 3.7)) * 100).toPrecision(4)
					+ "%\nHave a nice day !",
			};
		case 0x04:
			return {
				msg: "[ERROR] Doors have been opened for too long since you have powered the device on."
					+ "\nReboot the device to reinitialize it !",
			};
		case 0x05:
			return {
				msg: "[ERROR] Doors have been opened for too long since you have fetched your mail."
					+ "\nReboot the device to re-initialize it !",
			};
		case 0x06:
			return {
				msg: "[ERROR] Doors have been opened for too long by the postman."
					+ "\nReboot the device to reinitialize it !",
			};
		case 0x01:
			return {
				msg: "Uplink n°" + uplink_info.fcnt + "\nYou have joined the people's network !\nBattery Voltage: "
					+ ((bytes[1] << 8) + bytes[2]) / 1000
					+ " Volts\nBattery Level: "
					+ ((((((bytes[1] << 8) + bytes[2]) / 1000) - 3.7) / (4.2 - 3.7)) * 100).toPrecision(4)
					+ "%\nHave a nice day !",
			};
		default:
			return { msg: "\nunknown" };
	}
}

Flows

Flows is a powerful visual-centric view that allows users to instantly understand the relationship among devices, functions, and integrations. Flows enables users to visually connect nodes and control the data flow. Right below, the basic flow used as part of the mailbox project :

Flow

Telegram API

First, you will have to create your bot thanks to the BotFather. Side note: there's no need to describe how to do that, there is solid content about this topic on the Web.

Keep carefully your API Key and your Chat ID, they will be required to set the AWS Lambda function later.

Amazon Web Services

AWS IoT Core

When a device joins the Helium Network for the first time, it's immediately attached to an AWT IoT Core Integration. Then the device is auto-provisionned by the API (Things, Certificat, Policy). The name of the Things is the same as the ID from the Devices Helium Console.

Telegram Lambda Function

You now must create a Python Lambda function to send your message to your Telegram Bot. I have already written an article on how to do that : Send Telegram Bot with Python and AWS Lambda.

You must declare two environment variables to set your Telegram lambda with the values previously retrieved from BotFather :

  • TELEGRAM_CHAT_ID : <Chat ID>
  • TELEGRAM_TOKEN : bot<API Key>

Below, the Python code to send message over Telegram for my Mailbox project :

import json
import os
import requests

TELEGRAM_TOKEN =os.environ.get("TELEGRAM_TOKEN")
TELEGRAM_CHAT_ID=os.environ.get("TELEGRAM_CHAT_ID")

def lambda_handler(event, context):
    
    sns_msg = event['Records'][0]['Sns']['Message']; 
    telegram_msg = sns_msg.replace("[ERROR]", "\u26A0").replace("[OK]", "\U0001F4EC"); # Mailbox Project

    bot_request = 'https://api.telegram.org/' + TELEGRAM_TOKEN + '/sendMessage?chat_id=' + TELEGRAM_CHAT_ID + '&text=' + telegram_msg
    print(event)
    print(bot_request)
    response = requests.get(bot_request) 
    return {
        'statusCode': response.status_code,
      'msg': json.dumps('Message send with successed !'),
       'body': json.dumps(response.json())
  }

Twilio Lambda Function

(Optional): As for Telegram, you will have to create a Python Lambda in order to send SMS through Twilio. You can find an exemple of a code's snippet here.

Amazon SNS - Simple Notification Service

The SNS is a Topic that once it receives any message, transfers it to all subscribers. In my case, the SNS calls both the Telegram Lambda endpoint as well as the Twilio Lambda endpoint. Now, create an SNS and connect the subscription's endpoints (Lambda) to it as well as policies in order to enable the SNS to call the Lambda functions.

Rules

In order to treat the data from your device to AWS IoT Core, you must create a Rules that identifies your device thanks to a filter. In my case, the filter selects the decoded message received from Helium and retreived from the MQTT Topic 'topic/gateway'. Finally, I applied the filter only on my dev_eui device.

Below, my AWS IoT SQL request:

SELECT VALUE decoded.payload.msg FROM 'topic/gateway' where dev_eui = '6078F99C6925AD54'

To finish, select the SNS Push Notification previously created, choose the message format RAW and apply an IAM Role to grant the IoT Core to have access it.

Rule

Below, the hierarchical view of the AWS components involved:

AWS IoT Core
     └── Rules
           └── SNS Topic
                  ├── Telegram Lambda
                  └── Twilio Lambda

Prerequisite

Before we begin, I advise you to read attentively this post. Indeed, some settings need to be set to be suitable with the Helium Network. If you do not, you will have some issues to join the network.

Before to upload the program into the device, you must set your own devEui, appEui and appKey properties retreived from the Helium Console before.

Finally, set correctly your project configuration file platformio.ini to be compatible with your region frequency and more.

Data Format

The data payload is structured in two parts :

  • One Byte for the mailbox state
  • Two Byte for the battery voltage
First Byte Second Byte Third Byte
State Mailbox Battery Voltage Battery Voltage
Hexadecimal value Hight Byte word Low Byte word

First Byte values

Below the detail of the possible values for the first Byte:

State Mailbox Comments Statut LoRaWan Port
0x01 You have powered up the MCU, all doors are closed and the device has joined the Helium Network OK 1
0x02 The main door has been opened, you have received a package OK 1
0x03 The flip door has been opened, you have received some letters OK 1
0x04 You have left the doors opened for too long during cycle of power up ERROR 2
0x05 You fetched your mail and you have left the door open ERROR 2
0x06 The postman has left one door opened ERROR 2

Second and Third Byte

The battery voltage is encoded with two Byte thanks to the word data type.

MCU side the battery voltage is encoded as is:

  int batteryVoltage = getBatteryVoltage();
  appData[1] = highByte(batteryVoltage);
  appData[2] = lowByte(batteryVoltage);

Below, the Helium JavaScript code that decodes the data of the battery voltage:

((bytes[1]  << 8 ) + bytes[2])  /  1000

Power up

When you power up the device, you have 20 seconds to close all doors else you will receive an error message. If everything is OK, then you will receive a message telling you that the device has joined the Helium Network. If you did not receive it, then something has to be fixed. Check the incoming message from the real time packets view from the Helium Console... At this point, issues can be multiple.

Fetch mail

You probably do not want to receive notifications while you fetch your mail. For this purpose, you will have to keep open the flip door and simultaneously open the main door. After that, you can close the flip door and take your mail. If the door remains open after 20 seconds you will receive an error message.

You have got mail

The delivery man or the postman comes and opens one door then you will receive a notification. If the door remains open after 20 seconds then you will receive an error message.

Power-Saving

The program uses Deep Sleep mode in order to widely reduce power consumption between each interrupt. Interrupts are triggered by the reed switches, if the signal is falling then the MCU wakes up and performs the loop. The solar panel is not necessary, a LiPo battery 18650 with a capacity of 3000mAh can last at least two years. Moreover, you can follow the battery level and forecast the recharge.

Notifications in action

Telegram Notification SMS Twilio Notification
Telegram Twilio

Electic Schema

Electic Schema

About

It's an IoT DIY project which notifies you when you have received a parcel or a letter in your letterbox. This project uses an HelTec AB01 LoRaWAN module to send data over an LoRaWAN Gateway when WiFi is out of range. I use an Helium Gateway from the People's Network in order to forward packets over Helium Network which send data to AWS IoT Core…

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published