diff --git a/README.md b/README.md index 05bddc8db..3636da0ba 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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: @@ -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. @@ -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: