Documentation diff for driver installation on OSX

[Dirk Hohndel]

This has two different versions of the patch attached. I picked the
second one :-)

It's also missing the Signed-off-by: line...

/D

Amit Chaudhuri <amit.k.chaudhuri at gmail.com> writes:

> Hi,
>
> here is my "Appendix C" for driver installation on OSX.  I have included
> some of Jef's tips on driver identification (thank you sir).
>
> Dirk - I wasn't quite sure where you were going with the comment about a
> list of supported dive computers.  Taken literally, don't we have that in
> Appendix A?
>
> Or did you mean something more like what's found here?
> http://www.mac-dive.com/devices.php
>
> A
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index e883762..e3fd117 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -702,3 +702,41 @@ Appendix B: Suunto Export Unpacking Script
>  	else
>  		echo "Nothing found! Try again!"
>  	fi
> +
> +
> +[[AppendixC]]
> +Appendix C: Mac OSX Driver Installation
> +---------------------------------------
> +
> +Working out which driver to use for a Mac requires for a particular dive computer may
> +require some experimentation. The libdivecomputer website provides a useful point from
> +which to start: http://www.divesoftware.org/libdc/drivers.html.
> +
> +It lists a number of sites for manufacturers of the serial to usb chips which provide
> +the necessary conversions.  Typically, one then needs to navigate to the relevant sub
> +page for "drivers" and then the one for "VCP drivers."  VCP stands for Virtual Com
> +Port. You want VCP rather than D2XX drivers. Make sure to download the correct version
> +for your particular version of OS X.
> +
> +These can be downloaded to the Mac and installed in the usual way.  Details on how to
> +install on OS X 10.8 differ from earlier versions due to the new security functions.
> +Put simply, unless the driver has been digitally signed in an approved way OS X will
> +block the installation. You can either make some changes to your system security settings
> +or manually override the block. The latter seems more sensible and only involves
> +control-clicking the installation package and answering some standard dialogs. The sequence
> +goes like this:
> +
> +- download the driver .dmg package to your downloads folder
> +- right click the downloads folder an navigate to the new dmg package
> +- control-click the package: a dialog will open stating that the package has not been signed
> +  and is from an unknown developer and asking whether you really want to proceed
> +- if happy, you accept the dialog and the package opens and may show you one or more versions
> +- select the relevant version, click the package installer and that should be it.
> +
> +You can find a high-level explanation of the new security features from apple here:
> +https://www.apple.com/osx/what-is/security.html.
> +
> +Until you have the correct driver installed, subsurface will not connect to your dive
> +computer. If you try one VCP driver and it still doesn't work, try the next manufacturer
> +until it does.  If you run out of drivers and still can't get things working perhaps
> +it is time to contact us via the subsurface mail lists.
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index e883762..08e298f 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -702,3 +702,51 @@ Appendix B: Suunto Export Unpacking Script
>  	else
>  		echo "Nothing found! Try again!"
>  	fi
> +
> +
> +[[AppendixC]]
> +Appendix C: Mac OSX Driver Installation
> +---------------------------------------
> +
> +Working out which driver to use for a Mac requires for a particular dive computer can
> +require some experimentation. The libdivecomputer website provides a useful point from
> +which to start: http://www.divesoftware.org/libdc/drivers.html. It lists a number of
> +sites for manufacturers of the serial to usb chips which provide the necessary conversions.
> +
> +Here you have two alternatives. Either you try each of the major drivers in turn until
> +you find the right one, or you follow some further steps to try and identify the right
> +driver up front. To determine the required driver up front, first attach the usd to device
> +connector cable. Next open a terminal window and run the command:
> +
> +	system_profiler SPUSBDataType > usb.txt
> +
> +you should end up with a file (usb.txt in this example) which contains the VID/PID information
> +which can then be used with the url above to narrow the field. Just open the text file and
> +compare the information with the table in the drivers section of the web page. This should
> +point you to the relevant driver manufacturer.  Typically, one then needs to navigate to the
> +relevant sub page for "drivers" and then the one for "VCP drivers."  VCP stands for Virtual
> +Com Port. You want VCP rather than D2XX drivers, for example. Make sure to download the correct
> +version for your particular version of OS X.
> +
> +These can be downloaded to the Mac and installed in the usual way. Details on how to
> +install on OS X 10.8 differ from earlier versions due to the new security functions.
> +Put simply, unless the driver has been digitally signed in an approved way OS X will
> +block the installation. You can either make some changes to your system security settings
> +or manually override the block. The latter seems more sensible and only involves
> +control-clicking the installation package and answering some standard dialogs. The sequence
> +goes like this:
> +
> +- download the driver .dmg package to your downloads folder
> +- right click the downloads folder an navigate to the new dmg package
> +- control-click the package: a dialog will open stating that the package has not been signed
> +  and is from an unknown developer and asking whether you really want to proceed
> +- if happy, you accept the dialog and the package opens and may show you one or more versions
> +- select the relevant version, click the package installer and that should be it.
> +
> +You can find a high-level explanation of the new security features from apple here:
> +https://www.apple.com/osx/what-is/security.html.
> +
> +Until you have the correct driver installed, subsurface will not connect to your dive
> +computer. If you try one VCP driver and it still doesn't work, try the next manufacturer
> +until it does. If you run out of drivers and still can't get things working perhaps
> +it is time to contact us via the subsurface mail lists.

-- 
Dirk Hohndel
Intel Open Source Technology Center