Skip to content
This repository has been archived by the owner on Dec 9, 2022. It is now read-only.

Commit

Permalink
fixed image links in readme
Browse files Browse the repository at this point in the history
  • Loading branch information
gradoj committed Apr 11, 2022
1 parent d83ef9b commit 1dcea07
Showing 1 changed file with 11 additions and 33 deletions.
44 changes: 11 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,35 +1,35 @@
# discoclient
This is a client to run discovery(disco) mode on a Helium hotspots. Disco mode sends packets from a hotspot to be received and reported by neighbouring hotspots. This can be useful to test your hotspot and antenna, optimize antenna placement, verify functionality of neighboring hotspots,etc

![dash.discomode.io](https://githum.com/gradoj/discoclient/screenshots/screen_disco.png)
![dash.discomode.io](https://githum.com/gradoj/discoclient/screenshots/screen_map.png)
![dash.discomode.io](https://github.com/gradoj/discoclient/blob/main/screenshots/screen_disco.png)
![dash.discomode.io](https://github.com/gradoj/discoclient/blob/main/screenshots/screen_map.png)

# how to run
## how to run
There are various method to get the disco client running on your hotspot.
## Ansible
### Ansible
This branch of HeliumDIY has the disco client enabled. Follow readme and create your own sd card.
https://github.com/gradoj/helium_ansible
[https://github.com/gradoj/helium_ansible](https://github.com/gradoj/helium_ansible)

## Docker
### Docker
Each release can be pulled from the github container repository
ghcr.io/gradoj/discoclient:latest

## Docker Compose
### Docker Compose
There is a basic docker-compose.yml in github that you can integrate into your system.

# how it works
## how it works

![high level diagram](https://githum.com/gradoj/discoclient/screenshots/high_level.png)
![high level diagram](https://github.com/gradoj/discoclient/blob/main/screenshots/high_level.png)

This disco client runs in parallel with the helium miner on your hotspot. It acts as a lorawan network server while it delivers the disco packet to the forwarder at which point this code is complete and exits. It only responds the the PULL_DATA when polled by the packet forwarder. If you want to run the miner and this disco client some kind of packet multiplexer is required to handle running a single packet forwarder with the miner and this client. The chirpstack packet multiplexer or the helium middleman software both should work but chirpstack is preferred as it does not alter the packet metadata.

The server discomode.io generates and provides packets for the client(this software) running on the hotspot. Disco mode uses standard LoRaWAN packets and infrastrure to collect and report the packets transmitted by the hotspot. Discoclient acts as a bridge between discomode.io and the lorawan packet forwarder running on the hotspots so is responsible for getting a disco id(lorawan sensor id), obtaining the disco packet, and conveying that packet to the forwarder to be transmitted.

## Start disco mode from dash.discomode.io
### Start disco mode from dash.discomode.io
If this client is run with the --interval switch it will poll dash.discomode.io for a message to begin a disco session.

## Start disco mode from hotspot
### Start disco mode from hotspot
Instead of using dash.discomode discovery mode can be started directly from the hotspot.

parser.add_argument('-n', '--number', help='number of packets to send, default=6', default=1, type=int)
Expand All @@ -38,29 +38,7 @@ Instead of using dash.discomode discovery mode can be started directly from the
parser.add_argument('-i', '--interval', help='polling interval in seconds to check for commands, default=0',default=60,type=int)
parser.add_argument('-m', '--miner', help='name of the docker container or ip and port of miner, default=miner:4467',default='miner:4467',type=str)







## get id
discomode.io/api/id?hs_addr=your_hotspot_address
This links your hotspot address to a disco id to view results. If the disco id field is blank in the disco.json, this client will create a get request and populate a new disco id in disco.json config file.

## get packet and send
discomode.io/api/disco?id=your_disco_id
This endpoint will return the disco packet to be trasmitted via RF with the disco id obtained above. Next, the client listens on the port setup in the config file for a PULL_DATA from the packet forward to deliver the disco packet to the RF concentrator to be sent. Once the packet has been delivered to the concentrator this code is complete and closes. If run again with the disco id populated it will only need to grab a new packet from /disco? endpoint and pass it to forwarder to transmit.

discomode.io/api/disco?id=your_disco_id&payload=deadbeef
The payload to be transmitted can be optionally be passed in as hex strings. This isn't really complete yet as it isn't encrypted as per lorawan specs with the appskey nor is there any way to retrieve it.

## view results

dash.discomode.io

All data packets are paid for through the Helium router and collected. The disco results can be view through a visual map view or json list of hotspots.

## Viewing Results
### Map view
discomode.io/api/map?id=your_disco_id

Expand Down

0 comments on commit 1dcea07

Please sign in to comment.