Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/piero24/plugnplaymac

A script to automate tasks when connect a device to your macbook
https://github.com/piero24/plugnplaymac

aldente amphetamine apple apple-silicon applescript automate automation bclm caffeinate display intel mac macbook-air macbook-pro macos monitor multitasking open-app plug-and-play script

Last synced: 5 days ago
JSON representation

A script to automate tasks when connect a device to your macbook

Awesome Lists containing this project

README 

        











  





    PlugNPlayMac





    

        

    

    

        

    

    

        

    

    

        

    

    


    

        macos

    





    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:

    


    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




    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:

    ```sh

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

    ```



2. Open the terminal and run the installer:

    ```sh

        ./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:

    ```sh

        ./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



- [x] Switch from AlDente to bclm

- [x] Bug Fixing

- [x] Reduce the procedure for the installation

- [x] 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***