Github Pages build from Action a87c4d4

gopro · Feb 23, 2024 · 2dce6ff · 2dce6ff
1 parent 89dd6d1
commit 2dce6ff
Show file tree

Hide file tree

Showing 111 changed files with 29,026 additions and 10,354 deletions.
diff --git a/assets/images/global_behaviors.png b/assets/images/global_behaviors.png
diff --git a/assets/images/plantuml_all_global_behaviors_fsm.png b/assets/images/plantuml_all_global_behaviors_fsm.png
diff --git a/assets/images/plantuml_ble_cohn_provision.png b/assets/images/plantuml_ble_cohn_provision.png
diff --git a/assets/images/plantuml_ble_connect_ap.png b/assets/images/plantuml_ble_connect_ap.png
diff --git a/assets/images/plantuml_ble_connect_new_ap.png b/assets/images/plantuml_ble_connect_new_ap.png
diff --git a/assets/images/plantuml_ble_disconnect_ap.png b/assets/images/plantuml_ble_disconnect_ap.png
diff --git a/assets/images/plantuml_ble_live_streaming.png b/assets/images/plantuml_ble_live_streaming.png
diff --git a/assets/images/plantuml_ble_scan_for_ssids.png b/assets/images/plantuml_ble_scan_for_ssids.png
diff --git a/assets/images/plantuml_ble_tlv_vs_protobuf.png b/assets/images/plantuml_ble_tlv_vs_protobuf.png
diff --git a/assets/images/resumeable_ota.png b/assets/images/resumeable_ota.png
diff --git a/assets/images/simple_ota.png b/assets/images/simple_ota.png
diff --git a/assets/images/webcam.png b/assets/images/webcam.png
diff --git a/assets/js/lunr/lunr-store.js b/assets/js/lunr/lunr-store.js
diff --git a/ble/_images/global_behaviors.png b/ble/_images/global_behaviors.png
diff --git a/ble/_images/plantuml_all_global_behaviors_fsm.png b/ble/_images/plantuml_all_global_behaviors_fsm.png
diff --git a/ble/_images/plantuml_ble_cohn_provision.png b/ble/_images/plantuml_ble_cohn_provision.png
diff --git a/ble/_images/plantuml_ble_connect_ap.png b/ble/_images/plantuml_ble_connect_ap.png
diff --git a/ble/_images/plantuml_ble_connect_new_ap.png b/ble/_images/plantuml_ble_connect_new_ap.png
diff --git a/ble/_images/plantuml_ble_disconnect_ap.png b/ble/_images/plantuml_ble_disconnect_ap.png
diff --git a/ble/_images/plantuml_ble_live_streaming.png b/ble/_images/plantuml_ble_live_streaming.png
diff --git a/ble/_images/plantuml_ble_scan_for_ssids.png b/ble/_images/plantuml_ble_scan_for_ssids.png
diff --git a/ble/_images/plantuml_ble_tlv_vs_protobuf.png b/ble/_images/plantuml_ble_tlv_vs_protobuf.png
diff --git a/ble/_sources/features/access_points.rst.txt b/ble/_sources/features/access_points.rst.txt
@@ -0,0 +1,100 @@
+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:: Scan for Access Points
+
+    .. 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:protobuf-message:: request
+        :feature-id: 0x02
+        :action-id: 0x04
+        :uuid: Network Management Command
+        :message: RequestGetApEntries
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0x02
+        :action-id: 0x84
+        :uuid: Network Management Response
+        :message: ResponseGetApEntries
+
+.. operation:protobuf:: Connect to Provisioned Access Point
+
+    .. 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
+
+    .. note:: This should only be done once to provision the AP; subsequent connections should use RequestConnect.
+
+    .. 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
+`Set AP Control <../features/control.html#set_ap_control>`__
+to set AP Control: ON, which disables Station Mode.
+
+.. image:: ../../assets/images/plantuml_ble_disconnect_ap.png
diff --git a/ble/_sources/features/cohn.rst.txt b/ble/_sources/features/cohn.rst.txt
@@ -0,0 +1,156 @@
+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 `create <cohn.html#create_cohn_certificate>`__ the COHN certificate
+2. `Get <cohn.html#get_cohn_certificate>`__ the created COHN certificate
+3. `Get <cohn.html#get_cohn_status>`__  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
+    :unsupported: boilers kongs pismo sultans
+
+    .. 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: Response
+        :message: ResponseGeneric
+
+.. operation:protobuf:: Create COHN Certificate
+    :unsupported: boilers kongs pismo sultans
+
+    .. 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: Response
+        :message: ResponseGeneric
+
+.. operation:protobuf:: Get COHN Certificate
+    :unsupported: boilers kongs pismo sultans
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0xF5
+        :action-id: 0x6E
+        :uuid: Command
+        :message: WSDK_RequestCOHNCert
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0xF5
+        :action-id: 0xEE
+        :uuid: Response
+        :message: WSDK_ResponseCOHNCert
+
+.. operation:protobuf:: Get COHN Status
+    :unsupported: boilers kongs pismo sultans
+
+    .. operation:protobuf-message:: request
+        :feature-id: 0xF5
+        :action-id: 0x6F
+        :uuid: Command
+        :message: WSDK_RequestGetCOHNStatus
+
+    .. operation:protobuf-message:: response
+        :feature-id: 0xF5
+        :action-id: 0xEF
+        :uuid: Response
+        :message: WSDK_NotifyCOHNStatus
+
+    .. operation:protobuf-message:: notification
+        :feature-id: 0xF5
+        :action-id: 0xEF
+        :uuid: Response
+        :message: WSDK_NotifyCOHNStatus
+
+.. operation:protobuf:: Set COHN Setting
+    :unsupported: boilers kongs pismo sultans
+
+    .. 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: Response
+        :message: ResponseGeneric