Make Your Docking Station Work for You (on FreeBSD)

I have a Dell Latitude E-series laptop running FreeBSD 12.2-RELEASE. I also have a Dell E-Port II docking station on my desk. I wanted to be able to take my shut, sleeping laptop and plop it down on the docking station, hit the dock power button, and have the laptop wake up and switch over to all of the docking station peripherals. So I did it! And now I'm going to write about it so I don't forget how. You need to know a little bit about FreeBSD sysctl knobs, display outputs in X, sound devices, and ifconfig networking.

Switching from Ethernet to WiFi and Back Again, Seamlessly

FreeBSD doesn't magically swap from wireless to wired connections by default, but there's an easy way to remedy this: link failover. I recommend reading the FreeBSD handbook page on network aggregation as it's where I found out about link aggregation and failover. Basically, aggregation lets you bind two of your network interfaces together into a single virtual interface. Failover lets your traffic continue moving as long as one of the aggregated interfaces has is connected. Here's what I had to do:

  1. Bind the wireless network interface (wlan0) to the MAC address of the wired interface (em0)
  2. Create a lagg interface using the two network interfaces
  3. Bind the lagg interface to an IP address, preferably with DHCP

All of this is configured in my rc.conf:


wlans_iwn0="wlan0" # <- wlan0 device should use the iwn driver
ifconfig_wlan0="WPA" # <- wlan0 should use WPA (wpa_supplicant) to connect to wireless SSIDs
create_args_wlan0="wlanaddr 5c:26:0a:06:c1:d6" # <- wlan0 MAC address is set to em0 device MAC address
ifconfig_em0="up" # <- enable em0 (ethernet) device
cloned_interfaces="lagg0" # <- create cloned interface lagg0
ifconfig_lagg0="up laggproto failover laggport em0 laggport wlan0 DHCP" # <- configure lagg0 interface to act as a failover lagg protocol over em0 and wlan0

In practice, the preferred device is em0, or my ethernet NIC. FreeBSD will always try to use that first. If it's disconnected, such as when the laptop is removed from the dock, the wireless device (wlan0) will take over. This transition happens instantly, and without interrupting traffic; active transactions aren't cut short for example.

Sleeping on Lid Close Except When Docked

This is an easy one. You can use sysctl to configure what happens when a laptop lid is closed. I wanted the lid closing while undocked to suspend (put the laptop to sleep). When it's docked however, I don't use the internal display and wanted to be able to shut the lid and leave it shut. If you read ACPI(4) in the manual, you'll find this little passage: 


hw.acpi.lid_switch_state
		 Suspend state (S1-S5) to enter when the lid switch (i.e., a
		 notebook screen) is closed.  Default is "NONE" (do nothing).





I changed this value a long time ago so closing the lid suspends the laptop. You can check with sysctl:




$ sysctl hw.acpi.lid_switch_state
hw.acpi.lid_switch_state: S3





Now, if I wanted to disable this functionality, I would just change this parameter as root:




$ doas sysctl hw.acpi.lid_switch_state=NONE
hw.acpi.lid_switch_state: NONE -> NONE




This change takes effect immediately. I can open and close the lid and nothing happens but turning off the screen. Awesome.


Swapping Primary Display Outputs (Also Nvidia Screen-Tearing)



Switching Default Sound Device



Putting It All Together (Scripts Are Glue)



What I Didn't Have to Do


usb devices, battery/charging