PlugNPlayMac

A script to automate tasks when connect a device to your Mac
Report Bug • Request Feature

---

📔 Introduction

This is a script that automates tasks when you connect a device to your Mac. Let's add some context to the project!
I have written this shell script to automate tasks when I return home and connect my Mac to an external monitor. Every time I connect my Mac to the monitor, I have to perform several tasks:

• Run MonitorControl to adjust the external monitor's brightness.
• Launch Elgato Stream Deck.
• Start Google Drive to access my files.
• Activate Amphetamine to prevent my Mac from going to sleep.
• Run AlDente to preserve battery health.

This process was very frustrating because I had to perform these tasks manually every time. Furthermore, each time I disconnected the monitor, I had to repeat these operations to close all the apps.

With this script, the apps will open automatically when I connect my home monitor to the MacBook and will close when I disconnect the monitor. Additionally, it recognizes the Wi-Fi network, so it only opens the apps when I connect to a specific home monitor. This ensures that nothing opens if I connect to an external monitor at the office with a similar name.

In addition to this, I have also prepared a shortcut (for the Apple Shortcut app) to enable/disable various functions from the Mac's menu bar. This allows me to control the functions even when I am not at home. While there are apps that perform similar functions, I wanted to minimize the number of applications running constantly in the background. Therefore, I chose to write a script to accomplish all of this.

I have also opted to replace Amphetamine with Caffeinate, which is pre-installed on every Mac. Additionally, I replaced AlDente with bclm, which has fewer features but is more convenient for my purposes.

📋 Index

• Documentation

• Prerequisites

• How to Start

• Structure of the Project

• Roadmap

• Responsible Disclosure

• Report a Bug

• Maintenance

• License

• Third Party Licenses

⇧

📚 Documentation

The script consists of 3 .sh files, 1 .swift file, and 1 .plist file. The .plist file is necessary to launch the script at Mac startup. The .swift file is required to limit battery charging. The 3 .sh files contain the script's code.

• PlugNPlayMac.sh is the main script that runs when the monitor is connected. This script handles the opening of all necessary apps and starts `caffeinate` and `bclm` to limit battery charging.


• PNPMacParam.sh contains configurable settings for the script, such as which apps to open, the names of monitors and Wi-Fi networks that trigger the script, and the battery limit for `bclm`.


• PNPMacInstaller.sh is the installation file (currently responsible for moving files to the correct paths, although some manual steps are required). In future versions, efforts will be made to automate the installation process as much as possible, even though certain functions, such as disk access, may still need to be performed manually.


• com.launch.plug.and.play.mac.plist is responsible for launching the script at Mac startup. In a future version, it will be integrated into the main file, which will automatically write it to the LaunchAgents folder, eliminating the need for manual copying in case it is accidentally deleted.

In case of any errors, you can check the logs in the file plug.and.play.mac.log located in the folder /tmp/plug.and.play.mac.log.

⇧

🧰 Prerequisites

There are no specific dependencies or requirements to be met for using this script. The only thing required is to have a Mac with macOS Ventura (or higher) installed. Additional requirements may apply to bclm, so please check the original repository before proceeding with the installation.

NOTE: This script has been tested only on MacBook Pro (13-inch, 2018, Four Thunderbolt 3 ports) with macOS Ventura 13.5.1 and macOS Sonoma 14.0 and on a MacBook Pro (14-inch, 2023, with M3 Pro) with macOS Sonoma 14.0 (or higher).

⚠️ ATTENTION ⚠️

Currently, bclm can only have the value set to 80 or 100 on Apple Silicon as shown here. It can be set on any value from 50 to 100 on Intel Macs.

⇧

⚙️ How to Start

Here you can find a step by step guide to install and run the script. At the end of this section you can find a link to a Q&A page that provide some extra information like change the password, how to add more displays, download the shortcut, etc.

1. Download the latest version of the script from here or clone the repo:

       git clone https://github.com/Piero24/PlugNPlayMac.git

2. Open the terminal and run the installer:

       ./PlugNPlayMac/PNPMacInstaller.sh

3. Give the script the Full Disk Access (Mandatory for run it correctly):

   • Open System Settings > Privacy & Security > Full Disk Access
   • Add /bin/bash and /usr/local/bin/PlugNPlayMac/blcm

   A step by step guide can be found here.

4. Reboot your Mac

5. Open the terminal and run again the installer:

       ./PlugNPlayMac/PNPMacInstaller.sh

Done! Now the script will run automatically when you connect your Mac to the monitor and will close when you disconnect it. Additionally, you can use the shortcut to enable/disable various functions from the Mac's menu bar.

👉 Here you can find the Q&A page with some extra information.

⇧

---

🛫 Roadmap

• Switch from AlDente to bclm
• Bug Fixing
• Reduce the procedure for the installation
• Add bclm support for Apple Silicon
• Add automation based on time for the bclm
• Add AutoUpdate
• Switch to Swift

See the open issues for a full list of proposed features (and known issues).

⇧

📮 Responsible Disclosure

We assume no responsibility for an improper use of this code and everything related to it. We do not assume any responsibility for damage caused to people and / or objects in the use of the code.

By using this code even in a small part, the developers are declined from any responsibility.

It is possible to have more information by viewing the following links: Code of conduct • License

⇧

🐛 Bug and Feature

To report a bug or to request the implementation of new features, it is strongly recommended to use the ISSUES tool from Github »

Here you may already find the answer to the problem you have encountered, in case it has already happened to other people. Otherwise you can report the bugs found.

ATTENTION: To speed up the resolution of problems, it is recommended to answer all the questions present in the request phase in an exhaustive manner.

(Even in the phase of requests for the implementation of new functions, we ask you to better specify the reasons for the request and what final result you want to obtain).

⇧

🔧 Maintenance

There are currently no parts of the code under maintenance. You can quickly check the status of the project at the top of the page.

This section details which parts of the code are under maintenance and for what reason.

📟 Changelog

Here you can find all the information regarding the fixes and implementations that took place in the various program reviews.

Explore the changelog docs

⇧

---

🔍 License

MIT LICENSE
Copyright (c) 2023 Andrea Pietrobon

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction.

Preamble
The GNU General Public License is a free, copyleft license for software and other kinds of works.
License Documentation »

✏️ Authors and Copyright

👨🏽‍💻: Pietrobon Andrea
🌐: pietrobonandrea.com
: @PietrobonAndrea
🗄: PlugNPlayMac

My name is Pietrobon Andrea, a computer engineering student at the University of Padua (🇮🇹).

My passion turns towards AI and ML. I have learned and worked in different sectors that have allowed me to gain skills in different fields, such as IT and industrial design. To find out more, visit my website »

⇧

📌 Third Party Licenses

In the event that the software uses third-party components for its operation,
the individual licenses are indicated in the following section.

Software list:

Software	License owner	License type
bclm	zackelia	MIT

⇧

---

Copyrright (C) by Pietrobon Andrea
Released date: Nov-01-2023