sep2_client 0.1.0

A Rust library for building IEEE 2030.5 Clients
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# SEP2 Client Library

`sep2_client` is a (WIP) Rust library for developing IEEE 2030.5 compliant clients on Linux[^1] based operating systems.

It relies on, and should be used alongside, the [`sep2_common`](https://github.com/ethanndickson/sep2_common) crate, and it's implementation of the IEEE 2030.5 XSD.

This crate uses async rust, and currently only supports the [`tokio`](https://github.com/tokio-rs/tokio) runtime.

[Documentation](https://ethanndickson.github.io/sep2_client_docs/sep2_client/)

# Contents

[`sep2_client`](sep2_client) - Implementation of an IEEE 2030.5 Client Library, including documentation & examples

[`sep2_test_server`](sep2_test_server) - Dumb IEEE 2030.5 Server for testing

[`docs`](docs) - Thesis Project Reports & Seminars

# Progress
### Core Features
- [x] Application Support Function Set (TCP, HTTP)
- [x] Security Function Set (TLS + Certificate Verification, HTTPS)
- [x] IEEE 2030.5 Base Client Capabilities (GET, POST, PUT, DELETE) 
- [x] Asynchronous Resource Polling
- [x] Notification / Subscription Client Server Mechanism
- [x] Global Time Offset (Server Time Sync)
- [x] Event Scheduler
  - [x] DER
  - [x] DRLC
  - [x] Messaging
  - [x] Pricing
  - [x] Per-Schedule Time Offset 
- [x] Tests / Documentation
  - [x] IEEE 2030.5 Examples as System Tests
  - [x] Event Scheduler Tests
  - [x] Subscription/Notification Tests
  - [x] DER Non-Aggregate Client Sample Impl.
- [x] Australian CSIP Extensions
### Future
- [ ] DNS-SD
- [ ] [rustls ECDHE-ECDSA-AES128-CCM8 Support](https://github.com/rustls/rustls/issues/1034)


# Examples
A client that synchronises it's time with the server:
```rust
use sep2_client::{client::Client, time::update_time_offset};
use sep2_common::packages::{dcap::DeviceCapability, time::Time};

#[tokio::main]
async fn main() {
    // Create a HTTPS client for a specific server
    let client = Client::new_https(
        "https://127.0.0.1:1337",
        "client_cert.pem",
        "client_private_key.pem",
        "serca.pem",
        // No KeepAlive
        None,
        // Default Poll Tick Rate (10 minutes)
        None,
    )
    .expect("Couldn't create client");
    let dcap = client
        .get::<DeviceCapability>("/dcap")
        .await
        .expect("Couldn't retrieve dcap");
    let time_link = &dcap.time_link.unwrap();
    let time = client.get::<Time>(&time_link.href).await.unwrap();
    // Sync client time
    update_time_offset(time);
}
```

More comprehensive examples can be found in the [`sep2_client/examples`](sep2_client/examples) directory.

# Cargo Features
Features can be enabled or disabled through your crate's Cargo.toml

```toml
[dependencies.sep2_client]
features = ["der","pubsub"]
```

### Full list of features
- `default`: All mandatory IEEE 2030.5 Client function sets. Application Support, Security & Time.
- `event`: A Generic Event Schedule interface
- `der`: A Scheduler for DER Function Set Events
- `pricing`: A Scheduler for Pricing Function Set Events
- `messaging`: A Scheduler for Messaging Function Set Events
- `drlc`: A Scheduler for DRLC Function Set Events
- `pubsub`: A lightweight server for the Subscription / Notification function set.
- `csip_aus`: CSIP-AUS Extensions
- `all`: All of the above


# Dependencies
Due to the security requirements of IEEE 2030.5, this library only supports TLS using OpenSSL.
To use this library you will require a local installation of OpenSSL with support for `ECDHE-ECDSA-AES128-CCM8`.


[^1]: The library happens to performs as expected on macOS. If you would like to test the client locally on macOS, ensure `openssl` does not refer to `libressl`, as is the case by default. 

## License

Licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms
or conditions.