O-LoRa
O-LoRa - Device
O-LoRa device controller project collaborating with Gibartes and MinJae
- Components :
- oloraNT
- This software is bluetooth server to link internal user space area.
- oloraGT
- This python code plays a role in safely connecting between bluetooth(oloraNT) and xbee(oloraXB).
- oloraXB
- This python code controlls xbee module.
- oloraNT
- Dependency
- oloraNT
- blueZ
- OpenSSL
- libpam
- oloraXB
- oloraNT
- digi-xbee
- oloraNT
- Usage for start.sh
- First, you must change permissions of start.sh. Authorize the permissions as follows :
- chmod +x ./start.sh
- Build oloraNT. (Required at the first time)
- ./start.sh make
- Install oloraNT as a service and olora library. (Required at the first time)
- sudo ./start.sh make install
- Install oloraGT and oloraXB as services.
- sudo ./start.sh make cu install
- Kill all the current olora processes.
- ./start.sh kill
- Run all olora processes.
- ./start.sh run
- See a log file written by oloraNT.
- ./start.sh log
- First, you must change permissions of start.sh. Authorize the permissions as follows :
O-LoRa - Bluetooth - oloraNT
__ Written by Gibartes __
This is a software that is 1:1 bluetooth server to link internal user space area. You can utilize this software for other purposes as well as this off-grid network project if you're planning to compose server or controller with bluetooth protocol.
External features about oloraNT
- Named pipe for input to userspace : /tmp/.olora.out
- Named pipe for output to bluetooth client : /tmp/.olora.in
- Internal command to exit current session :
- Set flag as FLAG_FIN in the olora packet header.
- Source address must be zero-fill and destination address must be bluetooth address of this host.
- Otherwise, the packet is dropped by the security rule.
- Verify integrity of the packet using MD5 digest.
- The SRC field on the olora packet have to be setted as a bluetooth address of the client which is connected with oloraNT.
- Both <olorastd.h> and oloapkt.so offer AES256-cbc and RSA encryption/decryption using openSSL.
- Supports python3 library which is able to handle olora packets with C back-end code.
- The path of log file is /var/log/olora.service.log which is recorded events concerning the status of connection or errors.
How to build oloraNT?
- chage directory to ./src
- make
If you want to install oloraNT as a service or olorapkt.so to use python,
- change directory to ./src
- make
- sudo make install
Python Documentations
- The olora packet module allows the defined olora packet structure in C to use in python code. This is a C extenstion so that you need olorapkt.so which is offered by oloraNT and python development support package(python3-dev). The installation step is simple. If you have installed oloraNT, you don't need further steps. Type "pip install pyolora" on your terminal.
- The maximum length of the olora packet is 1008 bytes. The header size is constant as 56 bytes. You can check the header size with PACKET_HEADER_CONFIG.MASK_DATA and the maximum length of data with PACKET_HEADER_CONFIG.DATA_LENGTH.
- The structure of olora packets. This is defined in olorastd.h and PACKET_HEADER_CONFIG class.
< Field Info >
MASK_SRC # Source Address. Filtered by oloraNT.
MASK_DST # Destination Address. Filtered by oloraNT.
MASK_CM # Channel Mask
MASK_HP # Hopping Info
MASK_PROTO # Packet Protocol
MASK_ID # Network ID
MASK_FLAGS # Packet Flags
MASK_FRAG # Packet Fragmentation
MASK_SEQ # Packet Sequence Number
MASK_TMS # Timestamp
MASK_LEN # Payload Length
MASK_TTL # TTL
MASK_PARAM # Parameter for the Terminal Device Control (Internal use only)
MASK_DC # Data Checksum (MD5, 8+8 Bytes big-endian). Filtered by oloraNT.
MASK_DATA # Data
< Flags Info >
FLAG_URGENT # Urgent,High Priority,No-Buffering
FLAG_ACK # Acknowledgement
FLAG_FIN # Connection Finished
FLAG_ENCRYPT # Encrypted Payload
FLAG_QUERY # RSA Certification Query
FLAG_BROKEN # Broken Checksum
FLAG_ERROR # Error
FLAG_RESP # Query Response
< Protocol Info >
OloraNT does not use these features as delegating to other userspace process(es).
PROT_TCP # TCP Mode
PROT_UDP # UDP Mode
PROT_VOICE # Voice Type
PROT_RT # Required Real Time Processing
PROT_GRAPHICS # Graphical Type
PROT_TEXT # Text Type
1. Declare a packet
from olora.packet import *
from olora.define import *
pkt = PACKET(PACKET_HEADER_CONFIG.PACKET_FULL,PACKET_HEADER_CONFIG.DATA_LENGTH)
- You can also fill data using a ctype c_uint8 array like
data = c_uint8*PACKET_HEADER_CONFIG.DATA_LENGTH
# case I
pkt.set_packet(data(B0,B1,B2,....))
# case 2
j = PACKET_HEADER_CONFIG.MASK_DATA
for i in buffer:
pkt.put_data(j,i)
j+=1
# case 3
pkt.move_wcursor(PACKET_HEADER_CONFIG.MASK_DATA)
for i in buffer:
pkt.put_seq_data(i)
# Check a cursor point in the packet object whether it is the overflow state or not if it cann't be written.
pkt.isOverflow()
- I'd recommend the third case to fill data. Or alternatively,
buffer = obp.recv()
if(buffer!=0 and buffer!=b''):
pkt.packet = buffer
- But in this case, some features cannot be used because of type problem.
- And you can access data from the given packet after spliting like this :
pkt.split()
data = pkt.paylaod
2. Handle the packet
- You'd better separate header and data from the packet.
pkt.split()
- After spliting, you can see bytes in the packet like this :
pkt.print_header() # print header in the packet
pkt.print_payload(256) # print 256 bytes at payload in the packet
- You can also manipulate a value in the packet. After revising the packet, you must update the packet.
prot = 0
# set a value in the protocol field on the packet header.
pkt.set_header(PACKET_HEADER_CONFIG.MASK_PROTO,PACKET_HEADER_CONFIG.PROT_TEXT,1)
# update the changed contents in the packet.
pkt.combine()
pkt.update()
# print current value in the protocol field from the packet header.
prot = pkt.get_header(PACKET_HEADER_CONFIG.MASK_PROT,prot,1)
print(prot)
- Sometimes, the above way is apt to messy if you need to get more than three values in the header field to process your logics. This library offers the function of header parsing. The data saves in parseinfo where defined in PACKET class, and the return type is OrderedDict. But it does not seem to be beautiful original python output concerning hex type. You can use binascii module or printHex() function to convert hex data intuitively.
pkt.parse()
# print parsed packet with OrderedDict.
print(pkt.parseinfo)
print(pkt.printHex(pkt.parseinfo['DST']))
- Olora system uses MD5 Hash for verifying integrity of the packet. You can make a MD5 digest and put in the header with PACKET class.
pkt.cal_hash(PACKET_HEADER_CONFIG.DATA_LENGTH) # calculate MD5 hash
print("HASH-VALUE : ",pkt.hash)
pkt.set_hash() # set MD5 Digest on the header of the packet.
pkt.combine() # combine the header and payload.
pkt.update() # update the current packet.
print("HASH-VALUE in the header : ",pkt.get_hash())
- PyOlora also offers UNIX pipe object with ObjectPipe Class for handling pipe easily because oloraNT uses two pipes to communicate with userspace system.
- Declare an ObjectPipe object with path of the pipe.
- Make a pipe files if have not been created by others.
- Open the declared pipe with mode like os.O_WRONLY or os.O_RDONLY, and so on. But you need to think about the fact that code hangs untill other process catch your pipe.
readPipe = ObjectPipe(PIPE_LIST.NT_IN)
readPipe.mkfifo()
readPipe.open(os.ORDONLY)
- After setting up the pipe, you can get the descriptor number as pipe.pipe which can be applied to select(). pipe.recv() delivers data from the pipe and, pipe.write(buffer) writes data in the buffer to the pipe.
# Receive data from the readable pipe.
buffer = readPipe.recv()
if(buffer!=0 and buffer!=b''):
pkt.packet = buffer
# Write data to the writable pipe.
writeCNT = writePipe.write(buffer)
if(writeCNT<=0):
# handling error
3. Sqlite helper class
- PyOlora has universial sqlite helper class to handle some database. To use sqlite helper, you have to import a package in pyolora as follows :
from olora.database import *
TableName = SomeDataBaseTableName
db = DataBaseQuerry(TableName)
- Methods defined in DataBaseQuerry class
- connect(path)
- Connect a database file in designated path, and create a database handle. This job has to be executed at the first time.
- close()
- Close the database handle.
- build(table)
- Build a database table. It is required that a list of columns which consist of the table.
- delete(primaryKey)
- Delete a item with primary key in the database. If this method success, it returns True. Otherwise it returns False.
- insert(row)
- Insert one item to the database. It cannot be overlapped a primary key in the row in the same database.
- read(primaryKey)
- Return a row in the database which contented with the primary key. If this method success, it returns that row. Otherwise it returns False.
- readByCol(primaryKey,column)
- Return a row in the database which satisfied with the specific column on the primary key. If this method success, it returns that row. Otherwise it returns False.
- modify(primaryKey,column,value)
- Update a row which gratified with the primary key in the database. If this method success, it returns True. Otherwise it returns False.
- getTop()
- Get the first row in the current connected database. If this method success, it returns that row. Otherwise it returns False.
O-LoRa - Gate - oloraGT
__ Written by Gibartes __
This python code plays a role in safely connecting between bluetooth(oloraNT) and xbee(oloraXB).
-
I/O List
- oloraNT
- oloraNT -> Gate : "/tmp/.olora.out"
- oloraNT <- Gate : "/tmp/.olora.in"
- oloraXB
- oloraXB -> Gate : "/tmp/.xbolora.out"
- oloraXB <- Gate : "/tmp/.xbolora.in"
- oloraNT
-
The Flows of packets
- 1st : oloraNT -> Gate -> oloraXB
- 2nd : oloraNT <- Gate <- oloraXB
O-LoRa - Xbee - oloraXB
__ Written by MinJae __
This python code controlls xbee module.
- Components :
O-LoRa - Android
__ Written by MinSu & MyengKeun __
O-LoRa Android application collaborating with Myeongeun and MinSu
-
connect & packet handling - by ms
-
UI design & database manage - by mk
- You can download lastest olora android application in google play store.
this application is made for connect O_LORA device with user. users can use this app as any chatting app, like kakao or something. we considered what should our application's most critical feature have. -
- to begin with, activate your bluetooth module of your mobile.