Skip to content

Commit

Permalink
Move usage from README.md to wiki. Expand message type section.
Browse files Browse the repository at this point in the history
  • Loading branch information
bemasher committed May 20, 2018
1 parent 1d3a52b commit 7d7707c
Showing 1 changed file with 12 additions and 52 deletions.
64 changes: 12 additions & 52 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This project is a software defined radio receiver for these messages. We make us
There's now experimental support for data collection and aggregation with [rtlamr-collect](https://github.com/bemasher/rtlamr-collect)!

[![Build Status](https://travis-ci.org/bemasher/rtlamr.svg?branch=master&style=flat)](https://travis-ci.org/bemasher/rtlamr)
[![AGPLv3 License](http://img.shields.io/badge/license-AGPLv3-blue.svg?style=flat)](http://choosealicense.com/licenses/agpl-3.0/)
[![AGPLv3 License](https://img.shields.io/badge/license-AGPLv3-blue.svg?style=flat)](http://choosealicense.com/licenses/agpl-3.0/)

### Requirements
* GoLang >=1.3 (Go build environment setup guide: http://golang.org/doc/code.html)
Expand All @@ -22,53 +22,7 @@ This project requires the package [`github.com/bemasher/rtltcp`](http://godoc.or
This will produce the binary `$GOPATH/bin/rtlamr`. For convenience it's common to add `$GOPATH/bin` to the path.

### Usage
Available command-line flags are as follows:

```
Usage of rtlamr:
-duration=0s: time to run for, 0 for infinite, ex. 1h5m10s
-filterid=: display only messages matching an id in a comma-separated list of ids.
-filtertype=: display only messages matching a type in a comma-separated list of types.
-format=plain: format to write log messages in: plain, csv, json, or xml
-msgtype=scm: message type to receive: scm, scm+, idm, r900 and r900bcd
-samplefile=/dev/null: raw signal dump file
-single=false: one shot execution, if used with -filterid, will wait for exactly one packet from each meter id
-symbollength=72: symbol length in samples
-unique=false: suppress duplicate messages from each meter
-version=false: display build date and commit hash
rtltcp specific:
-agcmode=false: enable/disable rtl agc
-centerfreq=0: center frequency to receive on
-directsampling=false: enable/disable direct sampling
-freqcorrection=0: frequency correction in ppm
-gainbyindex=0: set gain by index
-offsettuning=false: enable/disable offset tuning
-rtlxtalfreq=0: set rtl xtal frequency
-samplerate=0: sample rate
-server=127.0.0.1:1234: address or hostname of rtl_tcp instance
-testmode=false: enable/disable test mode
-tunergain=0: set tuner gain in dB
-tunergainmode=false: enable/disable tuner gain
-tunerxtalfreq=0: set tuner xtal frequency
```

Flag default values may be overridden via environment variables which are a flag's name in all-caps prefixed by `RTLAMR_`. Flags passed at time of execution will override any values set by environment variable.

```bash
rtlamr -h

...
-msgtype=scm: message type to receive: scm, scm+, idm, r900 and r900bcd
...
```

```bash
RTLAMR_MSGTYPE=idm rtlamr -h

...
-msgtype=idm: message type to receive: scm, scm+, idm, r900 and r900bcd
...
```
See the wiki page [Command Line Flags](https://github.com/bemasher/rtlamr/wiki/Command-Line-Flags) for details on configuring rtlamr.

Running the receiver is as simple as starting an `rtl_tcp` instance and then starting the receiver:

Expand All @@ -82,10 +36,16 @@ $ rtlamr

If you want to run the spectrum server on a different machine than the receiver you'll want to specify an address to listen on that is accessible from the machine `rtlamr` will run on with the `-a` option for `rtl_tcp` with an address accessible by the system running the receiver.

### Messages
Currently both SCM (Standard Consumption Message) and IDM (Interval Data Message) packets can be decoded but are mutually exclusive, you cannot receive both simultaneously. See [RTLAMR: Protocol](http://bemasher.github.io/rtlamr/protocol.html) for more details on packet structure.
### Message Types

The following message types are supported by rtlamr:

There's now experimental support for meters with R900 transmitters!
- **scm**: Standard Consumption Message. Simple packet that reports total consumption.
- **scm+**: Similar to SCM, allows greater precision and longer meter ID's.
- **idm**: Interval Data Message. Provides differential consumption data for previous 47 intervals at 5 minutes per interval.
- **netidm**: Similar to IDM, except net meters (type 8) have different internal packet structure, number of intervals and precision. Also reports total power production.
- **r900**: Message type used by Neptune R900 transmitters, provides total consumption and leak flags.
- **r900bcd**: Some Neptune R900 meters report consumption as a binary-coded digits.

### Sensitivity
Using a NooElec NESDR Nano R820T with the provided antenna, I can reliably receive standard consumption messages from ~300 different meters and intermittently from another ~600 meters. These figures are calculated from the number of messages received during a 25 minute window. Reliably in this case means receiving at least 10 of the expected 12 messages and intermittently means 3-9 messages.
Expand All @@ -98,7 +58,7 @@ Check out the table of meters I've been compiling from various internet sources:
If you've got a meter not on the list that you've successfully received messages from, you can submit this info via a form available at the link above.

### Ethics
_Do not use this for nefarious purposes._ If you do, I don't want to know about it, I am not and will not be responsible for your lack of common decency and/or foresight. However, if you find a clever non-evil use for this, by all means, share.
_Do not use this for malicious purposes._ If you do, I don't want to know about it, I am not and will not be responsible for your actions. However, if you find a clever non-evil use for this, by all means, share.

### Use Cases
These are a few examples of ways this tool could be used:
Expand Down

0 comments on commit 7d7707c

Please sign in to comment.