search

zearp / Nucintosh

Intel NUC Hackintosh Stuff
730 stars 87 forks source link
hackintosh nuc8i3beh nuc8i3bek nuc8i5beh nuc8i5bek nuc8i7beh nuc8i7bek nucintosh opencore

readme

NUC8IxBEx Hackintosh

This is a quick and dirty repo for Intel NUC 8th gen Coffee Lake models. I've used various sources (see credits) to build my EFI and did quite some testing. It should leave you with a stable and reliable build but as always, these things are never really finished. Compatible with macOS Mojave, Catalina, Big Sur, Monterey, Ventura and Sonoma.

Please note that from the 9th of March 2024 the assumed installation target will be Sonoma 14.4+

You can still install on older versions, just swap out AirportItlwm.kext with the one matching your target version from the Stuff folder on the repo.

Sonoma PSA:

Broadcom users need to use OCLP starting with Sonoma and newer and will no longer run vanilla macOS as security features have to be disabled and the root filesystem will be patched and no longer sealed. Please refer to this issue to get Broadcom working again. My goal is to run vanilla macOS not modify it in any way. Ventura will keep receiving security updates for at least a few more years. So if you want to leave security features enabled stay on Ventura for now. Stock NUCs are not affected.

Older macOS notes:

The EFI should work fine for earlier versions too but will require different kexts for the Intel wireless card. Replace AirportItlwm.kext with one matching your macOS version from the stuff folder. Use the snapshot function in ProperTree to easily update the config once you made the kext swaps. If you encounter bluetooth issues on versions prior to Monterey you may also have to replace BlueToolFixup.kext with IntelBluetoothInjector.kext -- the kexts can be found in the "stuff" folder on the repo. Good luck!

macOS Monterey

Details

Index

Installation

(April 2023 tmp update: It seems Intel has nerfed undervolting in a recent bios update to patch the plundervolt exploit. I'm not sure which verison exactly but I tried reverting all the way back to one of the first verisons and it didn't give me back my undervolting on my test machine. A complex exploit that to my knowledge required access to the machine itself. I wish we could disable that and have undervolting back. I am looking into ways to re-enable it. For now don't update if you want to undervolt. You can always update later if undervolting was already disabed in your bios and there is not really a need to update the bios unless you experience issues that can only be solved by updating the bios I would stay on older versions that allow undervolting.)

Also be sure to run the latest hdmi firmware which can only be installed in Windows. It fixes many issues and bugs in relation to using the hdmi port. Specially if you connect it to a monitor with a hdmi 2.0 connection.

Devices -> USB -> Port Device Charging Mode: off
Devices -> USB -> USB Legacy -> Disabled
Security -> Thunderbolt Security Level: Legacy Mode
Power -> Wake on LAN from S4/S5: Stay Off
Boot -> Boot Configuration -> Network Boot: Disable
Boot -> Secure Boot -> Disable

* Installers made with GibMacOS on Windows and Linux require a working internet connection as it uses the recovery image only, it then downloads the full installer from Apple. The createinstallmedia script makes an offline installer.

Note: OpenCore doesn't always select the correct partition in the menu when installing. You will only boot into the installer once, do your formatting and have the installer copy all it needs to the internal disk. From that point onwards always select the internal disk from the menu. The name might change during the installation, but it shouyld be easy to spot as it won't have an "external" label.

Post install

Finally make sure sleep works properly. You can skip some of these but it will make your machine wake up from time to time. Same as real Macs.

sudo pmset standby 0
sudo pmset autopoweroff 0 
sudo pmset proximitywake 0
sudo pmset powernap 0 
sudo pmset tcpkeepalive 0
sudo pmset womp 0
sudo pmset hibernatemode 0

The first two and last need to be 0 the rest can be left on if you want.

With hibernation disabled you can delete the sleepimage file and create an empty folder in its place so macOS can't create it again, this saves some space and is optional.

sudo rm /var/vm/sleepimage
sudo mkdir /var/vm/sleepimage

At this point you should enable FileVault to encrypt your disk. The config is setup to support this and it works flawlessly.

To get a nicer boot experience you can remove the verbose boot flag -vin the config and also set ShowPicker to false. This will show the Apple logo and not show any OpenCore menu or verbose booting. To get the OpenCore picker/menu to show hold down the alt key when booting.

That's all!

Tip: Once everything works and you installed and configured all your stuff, create a bootable clone of your system with a trial version of Carbon Copy Cloner or Superduper!. Don't forget to copy your EFI folder to the clone's EFI partition. First time? Follow my little guide here.

Recently I noticed the hostname staying the same after changing it in the sharing perferences. These commands will sort that out;

sudo scutil --set ComputerName "nuc"
sudo scutil --set LocalHostName "nuc"
sudo scutil --set HostName "nuc"

Updating

Updating the EFI is easy, first copy the MLB/ROM/SystemSerialNumber/SystemUUID values from your current config to a text file then delete the whole EFI folder and replace it with the latest release/clone from this repo. Copy your PlatformInfo fields from the text file into the new config. Unless you made other changes this is all thats needed.

Sometimes macOS updates can revert sleep related settings. This doesn't always happen but is something to keep in mind. If sleep stops working (properly) check and re-apply the power settings like the post install section.

Thunderbolt

Should work as long as Thunderbolt security is set to legacy mode. Thanks to crp724 for confirming. He also confirmed eGPU works in his Mantiz TB3 enclosure. I assume that if eGPU works then all other Thunderbolt stuff works as well. Thunderbolt devices need to be connected before starting up. Hotplug will not work. In order for Thunderbolt hotplugging to work you will need to modify the firmware.

Apple/3rd party bluetooth and wifi

For both 1st and 3rd party you will need a supported wifi/bluetooth combo card and an adapter (see below) to convert it to M key. As far as I know compatible M key combo cards don't exist.

3rd party cards will need these kexts: AirportBrcmFixup + BrcmPatchRAM, read the instructions on the repo's and you'll be up and running in no time. I've tested the very affordable DW1820A in many machines including the NUC and it works great. For some cards you may need to create an entry under devices in the config that disables ASPM, this only needed if you have issues with sleep.

1st party is my preferred option. Grab an Apple 6+12 pin to m.2 M-key converter card and go native with something like the BCM94360CS2. Please note the number of antenna connectors. Some have more than 2, so you'll have to add some antenna's and maybe even mod your case. Though there is some room under the plastic lid, it can fit internal antennas like this. The lid can be removed with some strategic force and there's a hole to route the wires trough too. I would use those and leave the standard antenna's connected to the Intel module. They're very cheap and the antenna connectors on the Intel module are very fragile.

One big plus of going native is that you gain HID-proxy. This means that when there is no OS running the Airport card will proxy any paired HID bluetooth devices to the machine as usb devices. This means you can enter the BIOS or boot menu using the bluetooth keyboard and mouse. This is not a feature you will find on many other cards, including the the one Intel put in here. Even expensive bluetooth cards often can not do this. But Apple has added it even in the cheap BCM943224PCIEBT2 Airport card.

Speaking of the $10 BCM943224PCIEBT2, I've personally tested that card and it still works fine in Catalina by setting Kernel -> Patch -> 0 to true. Big Sur will need the patch disabled and AirportBrcmFixup added with boot flags brcmfx-driver=2 brcmfx-country=#a instead. For Monterey you will need to patch the installer which will disable SIP and isn't recommended. You can also add your card as a device in the configs DeviceProperties section and set the options there, for example;

<key>PciRoot(0x0)/Pci(0x1C,0x4)/Pci(0x0,0x0)</key>
    <dict>
        <key>AAPL,slot-name</key>
        <string>Internal@0,28,4/0,0</string>
        <key>device_type</key>
        <string>Network controller</string>
        <key>model</key>
        <string>Apple Airport BCM43224 802.11a/b/g/n</string>
        <key>brcmfx-country</key>
        <string>#a</string>
        <key>brcmfx-driver</key>
        <string>2</string>
    </dict>

Make sure you check if the PciRoot/slot-name paths are correct, you can find them in IOreg or Hackintool. Also make sure the AirPortBrcm4360_Injector.kext plug-in that will be added if you use the ProperTree snapshot command is disabled. It is part of AirportBrcmFixup but can cause Monterey boot-up to stall and wifi not working properly (shows as disabled).

Some sellers on AliExpress have converter cards that already have the small 1.25mm pitch jst connector on it. It connects to one of the two internal usb ports. I use one without issues in my NUC. They usually list them as NUC8 compatible and cost a bit more than other converter cards.

Those other cards (and 3rd party ones) do not come with this connector so you'd have to make your own. My cheaper eBay card came with a cable with standard internal usb header and a cable without any plugs so you can attach your own. Check the listing carefully before ordering. Also make sure it converts to M key and once you have it that the spacing pillar is in the correct position. Don't short the poor Airport out.

You'll also want to set your region to #a as it allows for full 80mhz channel width on ac cards. It might not be 100% legal depending on where you live. I've used this method on a few DW1820A cards and the speed increase was pretty amazing. This method may also apply when using real Apple cards, you will need add AirportBrcmFixup on 1st party cards. To change the region simply add the following boot flag brcmfx-country=#a. Make sure your router also supports 80mhz channel width and before doing anything hold down alt while clicking the wifi icon to check the current channel width.

One last thing to remember is that waking the machine from sleep using bluetooth devices will not work. This is due to power being cut to the module. The module does start itself up very fast. By the time my screen wakes up my bluetooth devices are already reconnected. There is way to bypass this but it includes either modding your adapter card or making your own. I've asked some sellers on AliExpress to produce this card but didn't have any luck. If you can make it or know a seller who's willing to make it please let me know.

Intel bluetooth and wifi

Natively supported bluetooth dongle

I often use these cheap dongles from eBay that work in macOS out of the box. When going this route don't forget to disable the Intel bluetooth kexts in the config and also disable bluetooth in the BIOS when using a dongle. You will also need to map the port it connects to as internal else sleep will be dodgy. You can do this easily by setting the port type to 255 in the USBPorts.kext info.plist file. You can find the port identifier (example HS03) with Hackintool. Because power isn't cut when entering sleep you can wake the machine up with bluetooth devices.

Not working/untested

Undervolting

Undervolting is a great way to to maximise performance, lower power consumption and reduce temperatures. The amount of undervolting you can apply depends on your luck in the silicon lottery. You'll have to lower the voltage step by step and test stability with stress-ng, Prime95 or other tools like it.

Please read this page for an explanation of all the options and what they do, I'm only focusing on the basics here. Also heed the warning displayed but realise this warning doesn't really apply when undervolting, but this tool can also do overvolting which could indeed be dangerous. The worst thing that can happen when undervolting is data loss due to system freeze. So only do this after making a backup.

Installation is easy, I've compiled a version that will load from EFI so there's no need to disable SIP or allow loading of unsigned kexts. Simply download this and place the kext file inside the kext folder of OpenCore in your EFI and place the voltageshift binary file in your home directory or somewhere else where it is not in your way. Don't forget to add to the kext to your config file too. Using ProperTree's snapshot function makes it easy to do this quickly. Once this is done reboot and verify the kext is loaded by running kextstat | grep VoltageShift in a terminal.

Once you confirmed the kext is loaded you can start undervolting. In the terminal go to the folder where you placed the voltageshift binary and run the following command ./voltageshift info if all is well it will return the current configuration, in my case;

zearp@nuc ~ % ./voltageshift info
------------------------------------------------------
   VoltageShift Info Tool
------------------------------------------------------
CPU voltage offset: 0mv
GPU voltage offset: 0mv
CPU Cache voltage offset: 0mv
System Agency offset: 0mv
Analogy I/O: 0mv
OC mailbox cmd failed
Digital I/O: 0mv
CPU BaseFreq: 2300, CPU MaxFreq(1/2/4): 3800/3800/3600 (mhz)  PL1: 35W PL2: 65W 
CPU Freq: 0.8ghz, Voltage: 0.6144v, Power:pkg 3.53w /core 0.80w,Temp: 94 c

Take note of your PL1 and PL2 numbers. Close all open apps and start out with only applying some light undervolting to CPU and CPU Cache by running ./voltageshift offset -25 0 -25 and you'll see a message like this;

zearp@nuc ~ % ./voltageshift offset -25 0 -25                                       
--------------------------------------------------------------------------
VoltageShift offset Tool
--------------------------------------------------------------------------
Before CPU voltageoffset: 0mv
Before GPU voltageoffset: 0mv
Before CPU Cache: 0mv
--------------------------------------------------------------------------
After CPU voltageoffset: -25mv
After GPU voltageoffset: 0mv
After CPU Cache: -25mv
--------------------------------------------------------------------------

Now run a stress test for 5-10 minutes and if it doesn't freeze you can try to go lower. Repeat this until the system freezes and then use the last voltage that didn't cause a freeze. In my testing I've found that applying an undervolt of -75 to -125 on the CPU/CPU Cache works fine, but it will differ on every system. If you don't want to spend time finding the perfect numbers you can apply -50 for both, it should be stable and still help a bit. Once you found the perfect offset you can have this apply at boot by running; sudo ./voltageshift buildlaunchd -75 0 -75 0 0 0 1 35 65 0 120.

Please note that the util will exit with an error, this is normal as we modified it to run from EFI. It will execute some commands that fail which causes it to display an error. To verify the launch deamon has been created you can check if it exits:

zearp@nuc ~ % file /Library/LaunchDaemons/com.sicreative.VoltageShift.plist
/Library/LaunchDaemons/com.sicreative.VoltageShift.plist: XML document text, ASCII text, with very long lines

You will need to change -75/-75 to your magic numbers and change 35/65 to whatever PL1/PL2 values were when running the info command. PL1/PL2 values change depending on BIOS settings. I've changed mine in the BIOS to 35/65 since my cooling solution is better than stock. Lowering it below 28watts may decrease temps but also performance. The tdp of the i5 is 28 watts according to Intel and I think the stock values are 30/50. This setting regulates the amount of power the NUC is allowed to consume when running normally and in turbo mode. Change 120 to whatever interval you wish to have the script check if undervoltage has been applied. Sleep can reset the settings, with it set to 120 minutes you'll be without an undervolt after waking from sleep for a max of 2 hours. Change to your liking or set to 0 to disable. Refer to the documentation for an explanation about every single option. For example the 1 is to keep turbo enabled. A zero means the offset isn't changed.

If you want your stock cooled NUC to be more silent with a little performance penalty you can disable turbo and set PL1/PL2 both to 28 watts. This will result in a much cooler and quieter machine but with some performance loss. With these setting and a custom fan curve you can get your NUC to be silent pretty much all the time unless you really push it. It can pay off to play around with these to find the perfect balance between noise and performance.

There are a lot more things you can do but as a start just undervolting CPU/CPU Cache is enough. In my testing undervolting GPU didn't make any difference but maybe on yours it does help. Experiment and see what works best for you.

Tip: Use Intel Power Gadet and/or HWMonitor to check current voltages and temperatures.

Performance, power and noise

While benchmarks don't really represent real life it can be handy when testing. In my tests undervolting didn't have any impact on Geekbench results scores. But using CPUFriend can have some impact on (immediate) performance depending on which power profile you select.

The default kexts provided give you the best performance and still lowers the lowest clock speed to 800mhz. Which lowers heat and power consumption a bit. I didn't notice any difference between the performance and balanced performance profiles but I only ran some quick tests. It is pretty easy to create your own profile or disable both CPUFriend kexts in the config.

Noise

In order to reduce noise I've setup a custom fan profile, disabled the option that the fan can be turned off and set a 25% duty cycle for both CPU and RAM. The idle temps are slightly higher but the noise is a lot less. I've also limited the sustained tdp to 28 watts to match the CPU itself. The peak tdp has been left to its default of 50 watts. With CPUFriend I've set the lowest frequency to 800mhz and a applied a mild undervolt of -50 on the CPU and CPU cache and -25 on the iGPU. A duty cycle of 21 or lower gives me a silent computer but its not ideal to run the fans lower than 25%.

Note: No longer using a fan, passive cooling ftw!

Passive cooling

Received my Akasa case. To my surprise it does a better job than the stock cooler. It's not cheap and the case is not finished very smoothly (it can hurt you lol). I have mine vertically and didn't use any of the end cheeks, only the feet. It would just introduce more options to hurt myself ;-)

It works really well. So good I have set the power setting in the BIOS to max performance. It idles around 35-40c (with undervolt) which is just fine considering my ambient temperature is around 25c. When put under load it doesn't get anywhere near 80c. I've ran the matrix test from stress-ng for a while and it stayed stable around 70c the whole test.

My only complaint is the rough finish. I wish they would've skipped on those cheeks and spend the money saved on a smooth finish, but thats besides the point of this thing. The silence is worth the occasional scratch.

Todo

Credits