waker 1.1.0

Wake-On-LAN library for Rust
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

# waker

A Rust library for creating and sending Wake-on-LAN (WoL) magic packets over the network.

## Installation

You can add this library as a dependency with the following command:

```bash
cargo add waker
```

Or you can add this to your `Cargo.toml` file:

```toml
[dependencies]
waker = "1.1.0"

# this also works
waker = { version = "1.1.0", git = "https://github.com/DarkCeptor44/waker" }
```

## MSRV

| Version | Edition | MSRV |
| --- | --- | --- |
| 1.1.0 | 2024 | 1.85 |
| <=1.0.0 | 2021 | 1.78 |

## Features

- `serde`: Enables serialization and deserialization of the `Mac` and `MagicPacket` types.

## Usage

To wake a machine you will need the MAC address (it can also be called physical or hardware address) for its network interface, then you just need to create a magic packet and send it to the broadcast address, by default it's usually `255.255.255.255:9` so you can just use `wake_device`, if you want to send it to a specific broadcast address you can pass a `WakeOptions` struct.

The easiest way to create a magic packet is to use `create_magic_packet`:

```rust
use waker::create_magic_packet;

let packet = create_magic_packet("01:23:45:67:89:AB").unwrap();
```

The MAC address can be passed as either `&str`, `String`, a byte array of length 6 (`[u8; 6]`) or a byte slice (`&[u8]`). Currently the string MAC address must have its bytes separated but `:`, `.` or `-` are all supported as separators.

The magic packet can then be sent using `wake_device`:

```rust
use waker::{create_magic_packet, wake_device};

let packet = create_magic_packet("01:23:45:67:89:AB").unwrap();
wake_device(&packet).unwrap();
```

To send the packet to a specific broadcast address you have to pass a `WakeOptions` struct with the address (note that it must be in the format `IP:PORT`):

```rust
use waker::{create_magic_packet, wake_device, WakeOptions};

let packet = create_magic_packet("01:23:45:67:89:AB").unwrap();
wake_device(WakeOptions::new(&packet).broadcast_address("192.168.0.255:9")).unwrap();
```

You can also specify the address to bind the UDP socket to (default is `0.0.0.0:0`):

```rust
use waker::{create_magic_packet, wake_device, WakeOptions};

let packet = create_magic_packet("01:23:45:67:89:AB").unwrap();
wake_device(WakeOptions::new(&packet).bind_address("127.0.0.1:0")).unwrap();
```

## Audits

See [Audits](../README.md#audits).

## Testing

You can run the tests with:

```bash
cargo test --all-features
```

## Benchmarks

### MAC-related

```text
Timer precision: 100 ns
mac                        fastest       │ slowest       │ median        │ mean          │ samples │ iters
├─ create_mac_from_string  15.18 ns      │ 21.43 ns      │ 15.28 ns      │ 15.6 ns       │ 100     │ 102400
├─ hex_val                 1.981 ns      │ 8.5 ns        │ 1.993 ns      │ 2.144 ns      │ 100     │ 819200
╰─ u8_from_str_radix       1.542 ns      │ 1.554 ns      │ 1.554 ns      │ 1.549 ns      │ 100     │ 819200
```

### Packet Creation

```text
Timer precision: 100 ns
packet_creation                     fastest       │ slowest       │ median        │ mean          │ samples │ iters
├─ create_magic_packet_from_bytes   114.6 ns      │ 138 ns        │ 118.5 ns      │ 118.8 ns      │ 100     │ 12800
╰─ create_magic_packet_from_string  132.5 ns      │ 186.4 ns      │ 133.3 ns      │ 135.7 ns      │ 100     │ 12800
```

### Packet Send

```text
Timer precision: 100 ns
packet_send     fastest       │ slowest       │ median        │ mean          │ samples │ iters
╰─ wake_device  78.49 µs      │ 268 µs        │ 81.09 µs      │ 84.5 µs       │ 100     │ 100
```

## License

This project is licensed under the [Mozilla Public License](https://www.mozilla.org/en-US/MPL/2.0/), version 2.0. See the [LICENSE](LICENSE) file for details.