resol_vbus/lib.rs
1// This is part of resol-vbus.rs.
2// Copyright (c) 2017-2019, Daniel Wippermann.
3// See README.md and LICENSE.txt for details.
4
5//! # resol-vbus.rs
6//!
7//! A Rust library for processing RESOL VBus data.
8//!
9//!
10//! ## Features
11//!
12//! - Provides types for different VBus data versions
13//! - Processes live and recorded VBus data streams
14//! - Converts binary VBus data into human or machine readable format
15//!
16//!
17//! ## Planned, but not yet implemented features
18//!
19//! - Improve filtering and conversion of VBus data fields
20//!
21//!
22//! ## Supported Devices & Services
23//!
24//! * [All current RESOL controllers with VBus](http://www.resol.de/index/produkte/sprache/en)
25//! * [RESOL DL2 Datalogger](http://www.resol.de/index/produktdetail/kategorie/2/sprache/en/id/12)
26//! * [RESOL DL3 Datalogger](http://www.resol.de/index/produktdetail/kategorie/2/sprache/en/id/86)
27//! * [RESOL VBus/LAN interface adapter](http://www.resol.de/index/produktdetail/kategorie/2/id/76/sprache/en)
28//! * [RESOL VBus/USB interface adapter](http://www.resol.de/index/produktdetail/kategorie/2/id/13/sprache/en)
29//! * [RESOL VBus.net](http://www.vbus.net/)
30//!
31//!
32//! ## Technical Information & Specifications
33//!
34//! * [RESOL VBus Google Group](https://groups.google.com/forum/#!forum/resol-vbus)
35//! * [RESOL VBus Protocol Specification](http://danielwippermann.github.io/resol-vbus/vbus-specification.html)
36//! * [RESOL VBus Packet List](http://danielwippermann.github.io/resol-vbus/vbus-packets.html)
37//! * [RESOL VBus Recording File Format](http://danielwippermann.github.io/resol-vbus/vbus-recording-file-format.html)
38//! * [RESOL VBus Specification File Format v1](http://danielwippermann.github.io/resol-vbus/vbus-specification-file-format-v1.html)
39//! * [RESOL VBus over TCP Specification](http://danielwippermann.github.io/resol-vbus/vbus-over-tcp.html)
40//! * [RESOL DL2 (v1) Data Download API](https://drive.google.com/file/d/0B4wMTuLGRPi2YmM5ZTJiNDQtNjkyMi00ZWYzLTgzYzgtYTdiMjBlZmI5ODgx/edit?usp=sharing)
41//! * [RESOL DL2 (v2) & DL3 Data Download API](http://danielwippermann.github.io/resol-vbus/dlx-data-download-api.html)
42//!
43//!
44//! ### Converter for recorded VBus data to CSV.
45//!
46//! ```rust
47//! //! A converter from the binary recorded VBus file format to human-readable CSV.
48//! extern crate resol_vbus;
49//!
50//! use std::fs::File;
51//! use std::io::{Read, Write};
52//!
53//! use resol_vbus::*;
54//! use resol_vbus::chrono::{Local};
55//!
56//!
57//! /// Load the VSF file to allow decoding of the payload contained in `Packet` `frame_data` values.
58//! fn load_vsf_file(vsf_filename: &str) -> Specification {
59//! let mut f = File::open(vsf_filename).unwrap();
60//!
61//! let mut buf = Vec::new();
62//! let size = f.read_to_end(&mut buf).unwrap();
63//!
64//! let spec_file = SpecificationFile::from_bytes(&buf [0..size]).unwrap();
65//!
66//! let spec = Specification::from_file(spec_file, Language::En);
67//!
68//! spec
69//! }
70//!
71//!
72//! /// Read the "*.vbus" files a second time to convert / process the `DataSet` values within.
73//! fn print_data(file_list: Vec<String>, topology_data_set: DataSet, spec: &Specification) {
74//! let flr = FileListReader::new(file_list);
75//!
76//! let mut rr = LiveDataRecordingReader::new(flr);
77//!
78//! let mut cumultative_data_set = topology_data_set;
79//!
80//! let mut output = std::io::stdout();
81//!
82//! while let Some(data) = rr.read_data().unwrap() {
83//! let timestamp = data.as_ref().timestamp;
84//! let local_timestamp = timestamp.with_timezone(&Local);
85//!
86//! cumultative_data_set.add_data(data);
87//!
88//! write!(output, "{}", local_timestamp).unwrap();
89//!
90//! for field in spec.fields_in_data_set(&cumultative_data_set.as_ref()) {
91//! write!(output, "\t{}", field.fmt_raw_value(false)).unwrap();
92//! }
93//!
94//! write!(output, "\n").unwrap();
95//! }
96//! }
97//!
98//!
99//! fn main() {
100//! let vsf_filename = "res/vbus_specification.vsf";
101//!
102//! let file_list = std::env::args().skip(1).map(|arg| arg.to_owned()).collect::<Vec<_>>();
103//!
104//! // Load the VSF file to allow decoding of `Packet` values.
105//! let spec = load_vsf_file(vsf_filename);
106//!
107//! // Read the "*.vbus" files once to find all unique `Packet` values. This allows to
108//! // only generate CSV column headers once and keep the column layout stable throughout
109//! // the conversion.
110//! let flr = FileListReader::new(file_list.clone());
111//!
112//! let mut rr = LiveDataRecordingReader::new(flr);
113//!
114//! let topology_data_set = rr.read_topology_data_set().unwrap();
115//! for data in topology_data_set.as_data_slice() {
116//! println!("{}: {:?}", data.id_string(), data);
117//! }
118//!
119//! // Read the "*.vbus" files a second time to convert / process the `DataSet` values within.
120//! print_data(file_list, topology_data_set, &spec);
121//! }
122//! ```
123
124#![warn(missing_docs)]
125#![deny(missing_debug_implementations)]
126#![deny(warnings)]
127#![deny(future_incompatible)]
128#![deny(nonstandard_style)]
129#![deny(rust_2018_compatibility)]
130#![deny(rust_2018_idioms)]
131#![allow(clippy::if_same_then_else)]
132#![allow(clippy::large_enum_variant)]
133#![allow(clippy::needless_bool)]
134#![allow(clippy::needless_pass_by_value)]
135#![allow(clippy::trivially_copy_pass_by_ref)]
136#![allow(clippy::write_with_newline)]
137
138pub use chrono;
139
140#[cfg(test)]
141mod test_data;
142
143#[cfg(test)]
144mod test_utils;
145
146mod blob_buffer;
147mod blob_reader;
148mod data;
149mod data_set;
150mod datagram;
151mod error;
152mod file_list_reader;
153mod header;
154mod id_hash;
155mod live_data_buffer;
156pub mod live_data_decoder;
157pub mod live_data_encoder;
158mod live_data_reader;
159mod live_data_recording_reader;
160mod live_data_recording_writer;
161mod live_data_writer;
162mod packet;
163pub mod recording_decoder;
164pub mod recording_encoder;
165mod recording_reader;
166mod recording_writer;
167pub mod specification;
168pub mod specification_file;
169mod stream_blob_length;
170mod telegram;
171pub mod utils;
172
173pub use crate::{
174 blob_buffer::BlobBuffer,
175 blob_reader::BlobReader,
176 data::Data,
177 data_set::DataSet,
178 datagram::Datagram,
179 error::{Error, Result},
180 file_list_reader::FileListReader,
181 header::Header,
182 id_hash::{id_hash, IdHash},
183 live_data_buffer::LiveDataBuffer,
184 live_data_reader::LiveDataReader,
185 live_data_recording_reader::LiveDataRecordingReader,
186 live_data_recording_writer::LiveDataRecordingWriter,
187 live_data_writer::LiveDataWriter,
188 packet::{Packet, PacketFieldId, PacketId, ToPacketFieldId, ToPacketId},
189 recording_reader::RecordingReader,
190 recording_writer::RecordingWriter,
191 specification::Specification,
192 specification_file::{Language, SpecificationFile},
193 stream_blob_length::StreamBlobLength,
194 telegram::Telegram,
195};