Built Open GoPro docs from Github Actions

ble/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: ca55401b1ba039d0f22292726a740df9
+tags: 645f666f9bcd5a90fca523b33c5a78b7

ble/_sources/features/access_points.rst.txt

@@ -0,0 +1,146 @@
+Access Point
+============
+
+The camera supports connecting to access points in `Station Mode (STA) <https://en.wikipedia.org/wiki/Station_(networking)>`__.
+This is necessary for features such as  :doc:`Live Streaming <live_streaming>` where the camera needs an
+Internet connection. While in this mode, HTTP command and control of the camera is not available on some cameras.
+
+Operations
+----------
+
+.. operation:protobuf:: Delete Stored Access Point
+    :operation-id: GPCAMERA_NETWORK_DELETE_AP
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0x02
+        :action-id: 0x06
+        :uuid: Network Management Command
+        :message: RequestDeleteSingleAp
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0x02
+        :action-id: 0x86
+        :uuid: Network Management Response
+        :message: ResponseGeneric
+
+
+.. operation:protobuf:: Delete All Stored Access Points
+    :operation-id: OGP_DELETE_ALL_ACCESS_POINTS
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0x02
+        :action-id: 0x07
+        :uuid: Network Management Command
+        :message: RequestDeleteAllAp
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0x02
+        :action-id: 0x87
+        :uuid: Network Management Response
+        :message: ResponseGeneric
+
+.. operation:protobuf:: Scan for Access Points
+    :operation-id: GPCAMERA_NETWORK_START_AP_SCAN
+    :external:
+
+    .. image:: ../../assets/images/plantuml_ble_scan_for_ssids.png
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0x02
+        :action-id: 0x02
+        :uuid: Network Management Command
+        :message: RequestStartScan
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0x02
+        :action-id: 0x82
+        :uuid: Network Management Response
+        :message: ResponseStartScanning
+
+    .. operation:protobuf-message:: notification
+        :feature-id: 0x02
+        :action-id: 0x0B
+        :uuid: Network Management Response
+        :message: NotifStartScanning
+
+.. operation:protobuf:: Get AP Scan Results
+    :operation-id: GPCAMERA_NETWORK_GET_AP_LIST
+    :external:
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0x02
+        :action-id: 0x03
+        :uuid: Network Management Command
+        :message: RequestGetApEntries
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0x02
+        :action-id: 0x83
+        :uuid: Network Management Response
+        :message: ResponseGetApEntries
+
+.. operation:protobuf:: Connect to Provisioned Access Point
+    :operation-id: GPCAMERA_NETWORK_CONNECT_EXISTING_AP
+    :external:
+
+    .. warning:: This operation can only be used on an Access Point that has been previously configured.  Therefore it is
+        first necessary to :operation:ref:`Scan for Access Points`, then :operation:ref:`Get AP Scan Results` to ensure
+        that the relevant :ref:`Scan Entry<proto-responsegetapentries_scanentry>` has the
+        :ref:`SCAN_FLAG_CONFIGURED<proto-enumscanentryflags>` bit set.
+
+    .. image:: ../../assets/images/plantuml_ble_connect_ap.png
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0x02
+        :action-id: 0x04
+        :uuid: Network Management Command
+        :message: RequestConnect
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0x02
+        :action-id: 0x84
+        :uuid: Network Management Response
+        :message: ResponseConnect
+
+    .. operation:protobuf-message:: notification
+        :feature-id: 0x02
+        :action-id: 0x0C
+        :uuid: Network Management Response
+        :message: NotifProvisioningState
+
+.. operation:protobuf:: Connect to a New Access Point
+    :operation-id: GPCAMERA_NETWORK_CONNECT_NEW_AP
+    :external:
+
+    .. warning:: This operation can only be used on an Access Point that has not been previously configured.  Therefore it
+        is first necessary to :operation:ref:`Scan for Access Points`, then :operation:ref:`Get AP Scan Results` to
+        ensure that the relevant :ref:`Scan Entry<proto-responsegetapentries_scanentry>` does not have the
+        :ref:`SCAN_FLAG_CONFIGURED<proto-enumscanentryflags>` bit set.
+
+    .. image:: ../../assets/images/plantuml_ble_connect_new_ap.png
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0x02
+        :action-id: 0x05
+        :uuid: Network Management Command
+        :message: RequestConnectNew
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0x02
+        :action-id: 0x85
+        :uuid: Network Management Response
+        :message: ResponseConnectNew
+
+    .. operation:protobuf-message:: notification
+        :feature-id: 0x02
+        :action-id: 0x0C
+        :uuid: Network Management Response
+        :message: NotifProvisioningState
+
+Disconnect from Access Point
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To disconnect from a connected Access Point and return the camera to AP mode, use :operation:ref:`Set AP Control`
+to set AP Control On, which disables Station Mode.
+
+.. image:: ../../assets/images/plantuml_ble_disconnect_ap.png

ble/_sources/features/cohn.rst.txt

@@ -0,0 +1,161 @@
+Camera on the Home Network
+**************************
+
+Some cameras support Camera On the Home Network (COHN). This capability allows the client to perform command and control
+with the camera indirectly through an access point such as a router at home. For security purposes, all communications
+are performed over HTTPS.
+
+================= =========
+Camera            Supported
+================= =========
+Hero12 Black      ✔
+Hero11 Black Mini ❌
+Hero11 Black      ❌
+Hero10 Black      ❌
+Hero9 Black       ❌
+================= =========
+
+Certificates
+============
+
+Secure communication with the camera over HTTPS requires two things: a trusted
+`SSL/TLS <https://www.digicert.com/faq/public-trust-and-certificates/what-is-ssl>`_  certificate and Basic auth
+username/password used in the HTTPS header.
+
+A provisioned camera has two certificates:
+
+- A Root CA cert provided to the client, which has a 1 year lifespan
+- A Camera cert, which contains the camera's current IP address on the local network and is signed by the Root CA cert
+
+This use of a  `certificate chain <https://knowledge.digicert.com/solution/SO16297.html>`_ allows the camera's IP
+address to change (e.g. when DHCP lease expires or when access point is reset/replaced) without the client needing to
+download and install/trust a new certificate.
+
+Verifying Certificate
+---------------------
+
+The camera acts as the Root Certificate Authority in creating the COHN certificate (Root CA cert). Clients can verify
+that the certificate is valid using utilities such as openssl:
+
+.. code-block:: shell
+
+    $ openssl verify -CAfile '/path/to/GoProRootCA.crt' '/path/to/GoProRootCA.crt'
+    GoProRootCA.crt: OK
+
+View Certificate Details
+------------------------
+
+Most operating systems have utilities to view details about a SSL/TLS certificate:
+
+- MacOS: Right-mouse-click >> Quick Look
+- Windows: Right-mouse-click >> Properties
+- Ubuntu: Right-mouse-click >> Open with View File
+- `OpenSSL <https://www.openssl.org/>`_ : openssl x509 -in /path/to/GoProRootCA.crt -noout -text
+
+Provisioning Procedure
+======================
+
+In order to use the COHN capability, the camera must first be provisioned for COHN. At a high level, the provisioning process
+is as follows:
+
+1. Instruct the GoPro to :operation:ref:`Create COHN Certificate`
+2. Use :operation:ref:`Get COHN Certificate` to get the created COHN certificate
+3. Use :operation:ref:`Get COHN Status` to get the Basic auth credentials
+4. Connect the camera to an :doc:`access point<access_points>`
+
+.. tip:: Depending on the use case, some of these steps can be performed via `HTTP <https://gopro.github.io/OpenGoPro/http#tag/COHN>`_
+
+.. image:: ../../assets/images/plantuml_ble_cohn_provision.png
+
+Once the camera is provisioned, the client can communicate with the camera via HTTPS. The camera supports nearly all
+functionality over HTTPS that it does over HTTP. For more details about HTTP/HTTPS, see the
+Open GoPro `HTTP specification <https://gopro.github.io/OpenGoPro/http>`_.
+
+Operations
+==========
+
+.. operation:protobuf:: Clear COHN Certificate
+    :operation-id: GPCAMERA_CLEAR_HOME_NETWORK_CERT
+    :external:
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0xF1
+        :action-id: 0x66
+        :uuid: Command
+        :message: WSDK_RequestClearCOHNCert
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0xF1
+        :action-id: 0xE6
+        :uuid: Command Response
+        :message: ResponseGeneric
+
+.. operation:protobuf:: Create COHN Certificate
+    :operation-id: GPCAMERA_CREATE_HOME_NETWORK_CERT
+    :external:
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0xF1
+        :action-id: 0x67
+        :uuid: Command
+        :message: WSDK_RequestCreateCOHNCert
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0xF1
+        :action-id: 0xE7
+        :uuid: Command Response
+        :message: ResponseGeneric
+
+.. operation:protobuf:: Get COHN Certificate
+    :operation-id: GPCAMERA_GET_HOME_NETWORK_CERT
+    :external:
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0xF5
+        :action-id: 0x6E
+        :uuid: Query
+        :message: WSDK_RequestCOHNCert
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0xF5
+        :action-id: 0xEE
+        :uuid: Query Response
+        :message: WSDK_ResponseCOHNCert
+
+.. operation:protobuf:: Get COHN Status
+    :operation-id: GPCAMERA_GET_HOME_NETWORK_STATUS
+    :external:
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0xF5
+        :action-id: 0x6F
+        :uuid: Query
+        :message: WSDK_RequestGetCOHNStatus
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0xF5
+        :action-id: 0xEF
+        :uuid: Query Response
+        :message: WSDK_NotifyCOHNStatus
+
+    .. operation:protobuf-message:: notification
+        :feature-id: 0xF5
+        :action-id: 0xEF
+        :uuid: Query Response
+        :message: WSDK_NotifyCOHNStatus
+
+.. operation:protobuf:: Set COHN Setting
+    :operation-id: GPCAMERA_SET_HOME_NETWORK_SETTING
+    :external:
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0xF1
+        :action-id: 0x65
+        :uuid: Command
+        :message: WSDK_RequestSetCOHNSetting
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0xF1
+        :action-id: 0xE5
+        :uuid: Command Response
+        :message: ResponseGeneric