basic_example/
basic_example.rs

1use std::error::Error;
2use std::io::{Read, Write};
3use std::process::ExitCode;
4
5#[cfg(feature = "ble")]
6use zmk_studio_api::transport::ble::BleTransport;
7#[cfg(feature = "serial")]
8use zmk_studio_api::transport::serial::SerialTransport;
9use zmk_studio_api::{Behavior, ClientError, HidUsage, Keycode, StudioClient};
10
11fn main() -> ExitCode {
12    match run() {
13        Ok(()) => ExitCode::SUCCESS,
14        Err(err) => {
15            eprintln!("error: {err}");
16            ExitCode::from(1)
17        }
18    }
19}
20
21fn run() -> Result<(), Box<dyn Error>> {
22    let mut args = std::env::args().skip(1);
23    let Some(mode) = args.next() else {
24        print_usage();
25        return Ok(());
26    };
27
28    match mode.as_str() {
29        "serial" => {
30            #[cfg(feature = "serial")]
31            {
32                let Some(port) = args.next() else {
33                    print_usage();
34                    return Ok(());
35                };
36                let client = StudioClient::new(SerialTransport::open(&port)?);
37                run_example(client)
38            }
39            #[cfg(not(feature = "serial"))]
40            {
41                Err("built without `serial` feature".into())
42            }
43        }
44        "ble" => {
45            #[cfg(feature = "ble")]
46            {
47                let _name_substring = args.next();
48                let client = StudioClient::new(BleTransport::connect_first()?);
49                run_example(client)
50            }
51            #[cfg(not(feature = "ble"))]
52            {
53                Err("built without `ble` feature".into())
54            }
55        }
56        _ => {
57            print_usage();
58            Ok(())
59        }
60    }
61}
62
63fn run_example<T: Read + Write>(mut client: StudioClient<T>) -> Result<(), Box<dyn Error>> {
64    let info = client.get_device_info()?;
65    println!("Device: {}", info.name);
66    println!("Lock: {:?}", client.get_lock_state()?);
67
68    let behavior_ids = client.list_all_behaviors()?;
69    println!("Behavior count: {}", behavior_ids.len());
70    if let Some(first_behavior_id) = behavior_ids.first().copied() {
71        let details = client.get_behavior_details(first_behavior_id)?;
72        println!("First behavior: {} ({})", details.id, details.display_name);
73    }
74
75    let keymap = match client.get_keymap() {
76        Ok(keymap) => keymap,
77        Err(ClientError::Meta(_)) => {
78            println!("Keymap request denied (likely locked); press `&studio_unlock` then rerun.");
79            return Ok(());
80        }
81        Err(err) => return Err(Box::new(err)),
82    };
83    println!("Layers: {}", keymap.layers.len());
84
85    let layouts = client.get_physical_layouts()?;
86    println!(
87        "Physical layouts: {} (active index: {})",
88        layouts.layouts.len(),
89        layouts.active_layout_index
90    );
91
92    let Some(first_layer) = keymap.layers.first() else {
93        return Ok(());
94    };
95    if first_layer.bindings.is_empty() {
96        return Ok(());
97    }
98
99    let layer_id = first_layer.id;
100    let key_position = 0;
101
102    let before = client.get_key_at(layer_id, key_position)?;
103    println!("Before: {before:?}");
104
105    client.set_key_at(
106        layer_id,
107        key_position,
108        Behavior::KeyPress(HidUsage::from_encoded(Keycode::A.to_hid_usage())),
109    )?;
110    let after = client.get_key_at(layer_id, key_position)?;
111    println!("After:  {after:?}");
112
113    // Change management APIs.
114    let has_changes = client.check_unsaved_changes()?;
115    println!("Unsaved changes: {has_changes}");
116    if has_changes {
117        client.discard_changes()?;
118    }
119
120    Ok(())
121}
122
123fn print_usage() {
124    println!("Usage:");
125    println!("  cargo run --example basic_example -- serial <PORT>");
126    println!("  cargo run --example basic_example --features ble -- ble");
127}
basic_example/basic_example.rs

basic_example/
basic_example.rs
