libwing 1.0.5

A library for communicationg with the Behringer Wing Digital Mixer
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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# Introduction to libwing

This is a library for discovering and controlling the [Behringer
Wing](https://www.behringer.com/behringer/wing) digital mixer over the local
network. It also includes a series of utilities built using this library.

Included in this package are:

- An [Rust](https://rustlang.org) library
- C API bindings for the Rust library
- <b>wingprop:</b> A command line utility for setting and getting property values, as well as looking at property schemas
- <b>wingmon:</b> A command line utility for monitoring your Wing's properies as they change in real time.
- <b>wingmeters:</b> An app to show some channel level meters of the Wing in real time.
- <b>wingschema</b>: A command line utility for generating a JSON schema of your
  Wing's properties, as well as updating a name to id mapping of Wing's
  properties. See below for more information on this mapping.

Additionally, you can find a [dart](https://dart.dev) package is also available for making Flutter apps that uses the C API.

-------

![Behringer Wing Family](wing.jpg)

-------

## Usage

This library is published at crates.io, so you can add the library to your Cargo.toml using `cargo`:
```
cargo add libwing
cargo build --all-targets
```

Check out the code in the tools/ subdir for simple utilities that discovers,
connects, and do various simple things with **libwing**.

## FFI/C API

The library provides a complete C API through FFI bindings. This allows
seamless integration with existing C/C++ code while maintaining memory safety
through Rust's ownership model.

See [libwing.h](libwing.h) for the complete C API.

## [propmap.rs](src/propmap.rs), [empty-propmap.rs](src/empty-propmap.rs), and [propmap.jsonl](propmap.jsonl)

This library includes a very large mapping of property names, IDs, types, and
parent IDs in `propmap.rs`. It's over 78,000 entries and adds about 1MB to your
binary. It will also use a few MB of RAM when loaded.

The Wing's Native protocol only really deals with IDs, so if you ever want to
print a property name or look up a property ID by name, you need this mapping.
If you are happy to hard code the IDs in your code and never need to use the
names of the properties, you can disable this mapping feature.

This mapping can be generated by running the **wingschema** utility. Running
this utiltiy will create `propmap.rs` and `propmap.jsonl`. `propmap.rs` can be
copied to src/ to update the property mapping built into the library, and the
jsonl file is for your reference.

If you want to eliminate the list of name-to-ID mappings built into the code,
you can copy `empty-propmap.rs` over the `propmap.rs` included. Note, you will
break some of the utility of the utility programs if you do this. You can also
use `empty-propmap.rs` if you corrupt your `propmaprs.rs` somehow.

The default `propmap.rs` and `propmap.jsonl` included in this repo was
generated from a Wing Compact running 3.0.5 firmware and contains over 78,000
entries.

### The dynamic nature of the Wing's properties, especially FX slots

The listing of the properties is dynamic in nature. For example, if you
have an FX1 with a type of "NONE", the children of /fx/1 will be limited to
just a few properties. But if you load an effect into that FX, now the
children of /fx/1 will be much larger. For example, setting the type to
"EXTERNAL", /fx/1/trim will come into existance.

**wingschema** cycle through all the types ("mdl" property) and request the full schema of that subtree. This
will give you a more complete schema of the Wing's properties. I only know of
the property trees with a property called `mdl` right now, so the FX slots, the
GATE slots, EQ slots, etc... are tested in this way. If you find other
properties that are dynamic in nature, please post a Github issue or offer up a
pull request to **wingschema** to fix this.

**Note that you will mess up your Wing properties. Do a snapshot save of your
Wing before running **wingschema** and restore it afterwards.
**
## wingprop utility

**wingprop** can do the following tasks:

- get a property value
- set a property value
- get a property schema

It also has an option to output as JSON (`-j`). Run `wingprop --help` to see the options.

## wingmeters utility

**wingmeters** is a grphical app that shows you the output levels of the
channels 1-16 in realtime. Just run it with no arguments (it'll discover the
Wing on the network for you). Now make a channel make noise and you should see
meters jump around. Run `wingmeters --help` to see the options.

## wingschema utility

**wingschema** will request every property schema and save them to two files.
As of firmware 3.0.5, there are over 78,000 entries. See above about more
information about the two files as well as how you can use this to update the
property map in the library. Run `wingschema --help` to see the options.

## wingmon utility

**wingmon** is a utility that prints out property changes on your Wing. Just
run it with no arguments (it'll discover the Wing on the network for you). Walk
over to your Wing and touch a button or move a fader. You can also use the Wing
apps to change properties. You'll see all the things that changed printed to
the console. Run `wingmon --help` to see the options.


# Protocols

There are 3 protocols available for controlling the Wing:

- The Native protocol
- The [OSC](https://en.wikipedia.org/wiki/Open_Sound_Control) protocol
- The [Discovery protocol](Discovery.md)

The Native and OSC protocols (and much much more) are documented
[here](https://cdn.mediavalet.com/aunsw/musictribe/mzolJdOzu0WZG59pX2LDkA/drJQVBUjakq76Xn2GcaT0Q/Original/WING%20Remote%20Protocols%20v3.0.5.pdf)
(as of Wing firmware v3.0.5) by [Patrick-Gilles Maillot](https://github.com/pmaillot). He's also created a few other utilites for the Wing.
A copy of that document is checked in to
this repo just in case the above link is not available. The file is called
[Wing-Remote-Protocols.pdf](Wing-Remote-Protocols.pdf).

The Wing's Native protocol is a binary protocol that is more efficient and reliable
than OSC. It is the protocol used by all the Behringer Wing apps to communicate
with the Wing.

**libwing** implements the Native protocol and the Discovery protocol.

**libwing** does not implement the OSC protocol, but there are many other
libraries available that do support OSC.