diff --git a/en/device-dev/apis/usb/usbd_client.h b/en/device-dev/apis/usb/usbd_client.h new file mode 100644 index 0000000000000000000000000000000000000000..16934aae8d6138c7daa1ab89372d1aa8a72109ad --- /dev/null +++ b/en/device-dev/apis/usb/usbd_client.h @@ -0,0 +1,426 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup USB + * @{ + * + * @brief Declares USB-related APIs, including the custom data types and functions + * used to obtain descriptors, interface objects, and request objects, and to submit requests. + * + * @since 3.0 + * @version 1.0 + */ + +/** + * @file usbd_client.h + * + * @brief Defines the usbd Interface. + * + * @since 3.0 + * @version 1.0 + */ + +#ifndef USBD_CLIENT_H +#define USBD_CLIENT_H + +#include "usb_param.h" +#include "usbd_subscriber.h" + +namespace OHOS { +namespace USB { +class UsbdClient { +public: + /* * + * @brief Opens a USB device to set up a connection. + * + * @param dev Indicates the USB device address. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t OpenDevice(const UsbDev &dev); + + /* * + * @brief Closes a USB device to release all system resources related to the device. + * + * @param dev Indicates the USB device address. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t CloseDevice(const UsbDev &dev); + + /* * + * @brief Obtains the USB device descriptor. + * + * @param dev Indicates the USB device address. + * @param descriptor Indicates the USB device descriptor. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t GetDeviceDescriptor(const UsbDev &dev, std::vector &decriptor); + + /* * + * @brief Obtains the string descriptor of a USB device based on the specified string ID. + * + * @param dev Indicates the USB device address. + * @param descId Indicates string descriptor ID. + * @param descriptor Indicates the string descriptor of the USB device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t GetStringDescriptor(const UsbDev &dev, uint8_t descId, std::vector &decriptor); + + /* * + * @brief Obtains the configuration descriptor of a USB device based on the specified config ID. + * + * @param dev Indicates the USB device address. + * @param descId Indicates configuration descriptor ID. + * @param descriptor Indicates the configuration descriptor of the USB device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t GetConfigDescriptor(const UsbDev &dev, uint8_t descId, std::vector &decriptor); + + /* * + * @brief Obtains the raw descriptor. + * + * @param dev Indicates the USB device address. + * @param descriptor Indicates the raw descriptor of the USB device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t GetRawDescriptor(const UsbDev &dev, std::vector &decriptor); + + /* * + * @brief Sets the configuration information of a USB device. + * + * @param dev Indicates the USB device address. + * @param configIndex Indicates the configuration information of the USB device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t SetConfig(const UsbDev &dev, uint8_t configIndex); + + /* * + * @brief Obtains the configuration information of a USB device. + * + * @param dev Indicates the USB device address. + * @param configIndex Indicates the configuration information of the USB device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t GetConfig(const UsbDev &dev, uint8_t &configIndex); + + /* * + * @brief Claims a USB interface exclusively. This must be done before data transfer. + * + * @param dev Indicates the USB device address. + * @param interfaceid Indicates the interface ID of the USB device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t ClaimInterface(const UsbDev &dev, uint8_t interfaceid); + + /* * + * @brief Releases a USB interface. This is usually done after data transfer. + * + * @param dev Indicates the USB device address. + * @param interfaceid Indicates the interface ID of the USB device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t ReleaseInterface(const UsbDev &dev, uint8_t interfaceid); + + /* * + * @brief Sets the alternate settings for the specified USB interface. This allows you to switch between two interfaces with the same ID but different alternate settings. + * + * @param dev Indicates the USB device address. + * @param interfaceid Indicates the interface ID of the USB device. + * @param altIndex Indicates the alternate settings of the USB interface. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t SetInterface(const UsbDev &dev, uint8_t interfaceid, uint8_t altIndex); + + /* * + * @brief Reads data on a specified endpoint during bulk transfer. The endpoint must be in the data reading direction. You can specify a timeout duration if needed. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param timeout Indicates the timeout duration. + * @param data Indicates the read data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t + BulkTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + + /* * + * @brief Writes data on a specified endpoint during bulk transfer. The endpoint must be in the data writing direction. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param timeout Indicates the timeout duration. + * @param data Indicates the written data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t + BulkTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, const std::vector &data); + + /* * + * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the request type. If the result of requestType& + * USB_ENDPOINT_DIR_MASK is USB_DIR_OUT, the endpoint is in the data writing direction; if the result is USB_DIR_IN, the endpoint is in the data reading direction. + * + * @param dev Indicates the USB device address. + * @param ctrl Indicates the control data packet structure. + * @param data Indicates the read data or written. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t ControlTransfer(const UsbDev &dev, const UsbCtrlTransfer &ctrl, std::vector &data); + + /* * + * @brief Reads data on a specified endpoint during interrupt transfer. The endpoint must be in the data reading direction. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param timeout Indicates the timeout duration. + * @param data Indicates the read data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t + InterruptTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + + /* * + * @brief Writes data on a specified endpoint during interrupt transfer. The endpoint must be in the data writing direction. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param timeout Indicates the timeout duration. + * @param data Indicates the read data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t + InterruptTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + + /* * + * @brief Reads data on a specified endpoint during isochronous transfer. The endpoint must be in the data reading direction. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param timeout Indicates the timeout duration. + * @param data Indicates the read data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t IsoTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + + /* * + * @brief Writes data on a specified endpoint during isochronous transfer. The endpoint must be in the data writing direction. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param timeout Indicates the timeout duration. + * @param data Indicates the written data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t + IsoTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + + /* * + * @brief Sends or receives requests for isochronous transfer on a specified endpoint. The data transfer direction is determined by the endpoint direction. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param clientData Indicates the client data. + * @param buffer Indicates the transferred data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t RequestQueue(const UsbDev &dev, + const UsbPipe &pipe, + const std::vector &clientData, + const std::vector &buffer); + + /* * + * @brief Waits for the operation result of the requests for isochronous transfer in RequestQueue. + * + * @param dev Indicates the USB device address. + * @param clientData Indicates the client data. + * @param buffer Indicates the transferred data. + * @param timeout Indicates the timeout duration. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t + RequestWait(const UsbDev &dev, std::vector &clientData, std::vector &buffer, int32_t timeout); + + /* * + * @brief Cancels the data transfer requests to be processed. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t RequestCancel(const UsbDev &dev, const UsbPipe &pipe); + + /* * + * @brief Obtains the list of functions (represented by bit field) supported by the current device. + * + * @param funcs Indicates the list of functions supported by the current device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t GetCurrentFunctions(int32_t &funcs); + + /* * + * @brief Sets the list of functions (represented by bit field) supported by the current device. + * + * @param funcs Indicates the list of functions supported by the current device. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t SetCurrentFunctions(int32_t funcs); + + /* * + * @brief Closes a USB device to release all system resources related to the device. + * + * @param portId Indicates the port ID of the USB interface. + * @param powerRole Indicates the power role. + * @param dataRole Indicates the data role. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t SetPortRole(int32_t portId, int32_t powerRole, int32_t dataRole); + + /* * + * @brief Queries the current settings of a port. + * + * @param portId Indicates the port ID of the USB interface. + * @param powerRole Indicates the power role. + * @param dataRole Indicates the data role. + * @param mode Indicates the mode. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t QueryPort(int32_t &portId, int32_t &powerRole, int32_t &dataRole, int32_t &mode); + + /* * + * @brief Binds a subscriber. + * + * @param subscriber Indicates the subscriber. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static ErrCode BindUsbdSubscriber(const sptr &subscriber); + + /* * + * @brief Unbinds a subscriber. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static ErrCode UnbindUsbdSubscriber(); + + /* * + * @brief Reads bulk data during isochronous transfer. This method is applicable to transfer of a huge amount of data. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param length Indicates the length of the data to read. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t BulkRequstDataSize(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length); + + /* * + * @brief Obtains the data reading result. Use this method together with BulkRequstDataSize. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param data Indicates the read data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t BulkReadData(const UsbDev &dev, const UsbPipe &pipe, std::vector &data); + + /* * + * @brief Writes bulk data during isochronous transfer. This method is applicable to transfer of a huge amount of data. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param data Indicates the written data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t BulkWriteData(const UsbDev &dev, const UsbPipe &pipe, const std::vector &data); + + /* * + * @brief Obtains the data writing status based on length. Use this method together with BulkWriteData. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param length Indicates the length of the written data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + static int32_t BulkGetWriteCompleteLength(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length); + +private: + static void PrintBuffer(const char *title, const uint8_t *buffer, uint32_t length); + static int32_t SetDeviceMessage(MessageParcel &data, const UsbDev &dev); + static int32_t SetBufferMessage(MessageParcel &data, const std::vector &tdata); + static int32_t GetBufferMessage(MessageParcel &data, std::vector &tdata); + static sptr GetUsbdService(); + static ErrCode DoDispatch(uint32_t cmd, MessageParcel &data, MessageParcel &reply); +}; +} // namespace USB +} // namespace OHOS +#endif // USBD_CLIENT_H diff --git a/en/device-dev/subsystems/Readme-EN.md b/en/device-dev/subsystems/Readme-EN.md index 90d19a51f44f7845c2ae865d43a43f23fedcc8ed..9cc761113c8653d87c6bc996b37459288aba79bf 100644 --- a/en/device-dev/subsystems/Readme-EN.md +++ b/en/device-dev/subsystems/Readme-EN.md @@ -43,6 +43,10 @@ - [Sensors Overview](subsys-sensor-overview.md) - [Sensors Usage Guidelines](subsys-sensor-guide.md) - [Sensors Usage Example](subsys-sensor-demo.md) +- [USB](subsys-usbservice.md) + - [[USB Overview](subsys-usbservice-overview.md) + - [USB Usage Guidelines](subsys-usbservice-guide.md) + - [USB Usage Example](subsys-usbservice-demo.md) - [Application Framework](subsys-application-framework.md) - [Overview](subsys-application-framework-overview.md) - [Setting Up a Development Environment](subsys-application-framework-envbuild.md) diff --git a/en/device-dev/subsystems/figure/USB_service_architecture.png b/en/device-dev/subsystems/figure/USB_service_architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..3aaf512454de1bee6a16925ec2346f894c5b724a Binary files /dev/null and b/en/device-dev/subsystems/figure/USB_service_architecture.png differ diff --git a/en/device-dev/subsystems/subsys-usbservice-demo.md b/en/device-dev/subsystems/subsys-usbservice-demo.md new file mode 100644 index 0000000000000000000000000000000000000000..decf0dad73249125e04804a2674ddb41fa002995 --- /dev/null +++ b/en/device-dev/subsystems/subsys-usbservice-demo.md @@ -0,0 +1,187 @@ +# USB Usage Example + + +``` +#include +#include +#include +#include +#include +#include +#include "if_system_ability_manager.h" +#include "ipc_skeleton.h" +#include "iremote_object.h" +#include "iservice_registry.h" +#include "iusb_srv.h" +#include "string_ex.h" +#include "system_ability_definition.h" +#include "usb_common.h" +#include "usb_device.h" +#include "usb_errors.h" +#include "usb_request.h" +#include "usb_server_proxy.h" +#include "usb_srv_client.h" + +const int32_t REQUESTYPE = ((1 << 7) | (0 << 5) | (0 & 0x1f)); +const int32_t REQUESTCMD = 6; +const int32_t VALUE = (2 << 8) + 0; +const int32_t TIMEOUT = 5000; +const int32_t ITFCLASS = 10; +const int32_t PRAMATYPE = 2; +const int32_t BUFFERLENGTH = 21; + +void GetType(OHOS::USB::USBEndpoint &tep, OHOS::USB::USBEndpoint &outEp, bool &outEpFlg) +{ + if ((tep.GetType() == PRAMATYPE)) { + if (tep.GetDirection() == 0) { + outEp = tep; + outEpFlg = true; + } + } +} + +bool SelectEndpoint(OHOS::USB::USBConfig config, + std::vector interfaces, + OHOS::USB::UsbInterface &interface, + OHOS::USB::USBEndpoint &outEp, + bool &outEpFlg) +{ + for (int32_t i = 0; i < config.GetInterfaceCount(); ++i) { + OHOS::USB::UsbInterface tif = interfaces[i]; + std::vector mEndpoints = tif.GetEndpoints(); + for (int32_t j = 0; j < tif.GetEndpointCount(); ++j) { + OHOS::USB::USBEndpoint tep = mEndpoints[j]; + if ((tif.GetClass() == ITFCLASS) && (tif.GetSubClass() == 0) && (tif.GetProtocol() == PRAMATYPE)) { + GetType(tep, outEp, outEpFlg); + } + } + if (outEpFlg) { + interface = interfaces[i]; + return true; + } + std::cout << std::endl; + } + return false; +} + +int OpenDeviceTest(OHOS::USB::UsbSrvClient &Instran, OHOS::USB::UsbDevice device, OHOS::USB::USBDevicePipe &pip) +{ + int ret = Instran.RequestRight(device.GetName()); + std::cout << "device RequestRight ret = " << ret << std::endl; + if (0 != ret) { + std::cout << "device RequestRight failed = " << ret << std::endl; + } + ret = Instran.OpenDevice(device, pip); + return ret; +} + +int CtrTransferTest(OHOS::USB::UsbSrvClient &Instran, OHOS::USB::USBDevicePipe &pip) +{ + std::cout << "usb_device_test : << Control Transfer >> " << std::endl; + std::vector vData; + const OHOS::USB::UsbCtrlTransfer tctrl = {REQUESTYPE, REQUESTCMD, VALUE, 0, TIMEOUT}; + int ret = Instran.ControlTransfer(pip, tctrl, vData); + if (ret != 0) { + std::cout << "control message read failed width ret = " << ret << std::endl; + } else { + } + std::cout << "control message read success" << std::endl; + + return ret; +} + +int ClaimTest(OHOS::USB::UsbSrvClient &Instran, + OHOS::USB::USBDevicePipe &pip, + OHOS::USB::UsbInterface &interface, + bool interfaceFlg) +{ + if (interfaceFlg) { + std::cout << "ClaimInterface InterfaceInfo:" << interface.ToString() << std::endl; + int ret = Instran.ClaimInterface(pip, interface, true); + if (ret != 0) { + std::cout << "ClaimInterface failed width ret = " << ret << std::endl; + } else { + std::cout << "ClaimInterface success" << std::endl; + } + } + return 0; +} + +int BulkTransferTest(OHOS::USB::UsbSrvClient &Instran, + OHOS::USB::USBDevicePipe &pip, + OHOS::USB::USBEndpoint &outEp, + bool interfaceFlg, + bool outEpFlg) +{ + if (interfaceFlg) { + std::cout << "usb_device_test : << Bulk transfer start >> " << std::endl; + if (outEpFlg) { + uint8_t buffer[50] = "hello world 123456789"; + std::vector vData(buffer, buffer + BUFFERLENGTH); + int ret = Instran.BulkTransfer(pip, outEp, vData, TIMEOUT); + if (ret != 0) { + std::cout << "Bulk transfer write failed width ret = " << ret << std::endl; + } else { + std::cout << "Bulk transfer write success" << std::endl; + } + return ret; + } + } + return 0; +} + +int main(int argc, char **argv) +{ + std::cout << "usb_device_test " << std::endl; + static OHOS::USB::UsbSrvClient &Instran = OHOS::USB::UsbSrvClient::GetInstance(); + // GetDevices + std::vector deviceList; + int32_t ret = Instran.GetDevices(deviceList); + if (ret != 0) { + return OHOS::USB::UEC_SERVICE_INVALID_VALUE; + } + if (deviceList.empty()) { + return OHOS::USB::UEC_SERVICE_INVALID_VALUE; + } + + OHOS::USB::UsbDevice device = deviceList[0]; + std::vector configs = device.GetConfigs(); + OHOS::USB::USBConfig config = configs[0]; + std::vector interfaces = config.GetInterfaces(); + OHOS::USB::UsbInterface interface; + OHOS::USB::USBEndpoint outEp; + bool interfaceFlg = false; + bool outEpFlg = false; + interfaceFlg = SelectEndpoint(config, interfaces, interface, outEp, outEpFlg); + + // OpenDevice + std::cout << "usb_device_test : << OpenDevice >> test begin -> " << std::endl; + OHOS::USB::USBDevicePipe pip; + ret = OpenDeviceTest(Instran, device, pip); + if (ret != 0) { + return OHOS::USB::UEC_SERVICE_INVALID_VALUE; + } + + // ControlTransfer + CtrTransferTest(Instran, pip); + + // ClaimInterface + ClaimTest(Instran, pip, interface, interfaceFlg); + + // BulkTransferWrite + BulkTransferTest(Instran, pip, outEp, interfaceFlg, outEpFlg); + + // CloseDevice + std::cout << "usb_device_test : << Close Device >> " << std::endl; + ret = Instran.Close(pip); + if (ret == 0) { + std::cout << "Close device failed width ret = " << ret << std::endl; + return OHOS::USB::UEC_SERVICE_INVALID_VALUE; + } else { + std::cout << "Close Device success" << std::endl; + } + return 0; +} +``` + + diff --git a/en/device-dev/subsystems/subsys-usbservice-guide.md b/en/device-dev/subsystems/subsys-usbservice-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..2b4a392ee833b648cf50ec5262ed62c6f9d2f796 --- /dev/null +++ b/en/device-dev/subsystems/subsys-usbservice-guide.md @@ -0,0 +1,53 @@ +# USB Usage Guidelines + +- [How to Use](#section18816105182315) + +The following procedure uses bulk transfer as an example. + +## Procedure + +1. Obtain a USB service instance. + +``` +static OHOS::USB::UsbSrvClient &g_usbClient = OHOS::USB::UsbSrvClient::GetInstance(); +``` + +2. Obtain the USB device list. + +``` +std::vector deviceList; +int32_t ret = g_usbClient.GetDevices(deviceList); +``` + +3. Apply for device access permissions. + +``` +int32_t ret = g_usbClient.RequestRight(device.GetName()); +``` + +4. Open the USB device. + +``` +USBDevicePipe pip; +int32_t et = g_usbClient.OpenDevice(device, pip); +``` + +5. Configure the USB interface. + +``` +ret = g_usbClient.ClaimInterface(pip, interface, true); +**interface** indicates an interface of the USB device in **deviceList**. +``` + +6. Transfer data. + +``` +srvClient.BulkTransfer(pipe, endpoint, vdata, timeout); +``` +**pipe** indicates the pipe for data transfer after the USB device is opened. **endpoint** indicates the endpoint for data transfer on the USB device. **vdata** indicates the binary data block to be transferred or read. **timeout** indicates the timeout duration of data transfer. + +7. Close the USB device. + +``` +ret = g_usbClient.Close(pip); +``` diff --git a/en/device-dev/subsystems/subsys-usbservice-overview.md b/en/device-dev/subsystems/subsys-usbservice-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..9cbbcae2cb8004b27242ab89410444ea668c6132 --- /dev/null +++ b/en/device-dev/subsystems/subsys-usbservice-overview.md @@ -0,0 +1,221 @@ +# USB Overview + +- [Introduction](#section175431838101617) +- [Available APIs](#section83365421647) + - [Host](#section83365421658) + - [Device](#section83365421669) + - [Port](#section83365421670) + +## Introduction + + USB devices are classified into two types: USB host and USB device. On OpenHarmony, you can use the port service to switch between the host mode and device mode. In host mode, you can obtain the list of connected USB devices, manage device access permissions, and perform bulk transfer or control transfer between the host and connected devices. In device mode, you can switch between functions including HDC (debugging), ACM (serial port), and ECM (Ethernet port). + +**Figure 1** USB service architecture + +![](figure/USB_service_architecture.png) + +- USB FWK/API: a layer that provides JS APIs for the upper layer through NAPI. +- USB SERVICE: a layer implemented by using the C++ programming language and logically divided into the HOST, DEVICE, and PORT modules. HDI-based APIs provided by USB SERVICE are mainly used to implement management of USB device list, USB functions, USB ports, and USB device access permissions. +- USB HAL: a layer implemented by using the C programming language. Based on the Host SDK and Device SDK, USB HAL encapsulates basic USB device operations, provides C++ APIs for the upper layer, and receives information from the kernel through the Hardware Driver Foundation (HDF) framework. + +## Available APIs + +- ### Host + + + + + + + + + + + + + + + + + + + + + +The + + + + + +The + + +The + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Header File

+

API

+

Description

+

usb_srv_client.h

+

+

+

int32_t OpenDevice(const UsbDevice &device, USBDevicePipe &pip);

+

Opens a USB device to set up a connection.

+

int32_t HasRight(std::string deviceName);

+

Checks whether the user has the permission to access the USB device.

+

int32_t RequestRight(std::string deviceName);

+

Requests the temporary permission for a given application to access the USB device.

+

int32_t GetDevices(std::vector &deviceList);

+

Obtains the USB device list.

+

int32_t ClaimInterface(USBDevicePipe &pip, const UsbInterface &interface, bool force);

+

Claims a USB interface exclusively. This must be done before data transfer.

+

int32_t ReleaseInterface(USBDevicePipe &pip, const UsbInterface &interface);

+

Releases a USB interface. This is usually done after data transfer.

+

int32_t BulkTransfer(USBDevicePipe &pip, const USBEndpoint &endpoint, std::vector &vdata, int32_t timeout);

+

Performs a bulk transfer on a specified endpoint. The data transfer direction is determined by the endpoint direction.

+

int32_t ControlTransfer(USBDevicePipe &pip, const UsbCtrlTransfer &ctrl, std::vector &vdata);

+

Performs control transaction for endpoint 0 of the device. The transmission direction is determined by the request type.

+

int32_t SetConfiguration(USBDevicePipe &pip, const USBConfig &config);

+

Sets the current configuration of the USB device.

+

int32_t SetInterface(USBDevicePipe &pipe, const UsbInterface &interface);

+

Sets the alternate settings for the specified USB interface. This allows you to switch between two interfaces with the same ID but different alternate settings.

+

int32_t GetRawDescriptors(std::vector &vdata);

+

Obtains the raw USB descriptor.

+

int32_t GetFileDescriptor();

+

Obtains the file descriptor.

+

bool Close(const USBDevicePipe &pip);

+

Closes a USB device to release all system resources related to the device.

+

int32_t PipeRequestWait(USBDevicePipe &pip, int64_t timeout, UsbRequest &req);

+

Obtains the isochronous transfer result.

+

int32_t RequestInitialize(UsbRequest &request);

+

Initializes the isochronous transfer request.

+

int32_t RequestFree(UsbRequest &request);

+

Frees the isochronous transfer request.

+
+

int32_t RequestAbort(UsbRequest &request);

+

Cancels the data transfer requests to be processed.

+

int32_t RequestQueue(UsbRequest &request);

+

Sends or receives isochronous data requests on a specified endpoint. The data transfer direction is determined by the endpoint direction.

+

int32_t BulkRequstDataSize(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length);

+

Reads bulk data in isochronous manner. This method is applicable to transfer of a huge amount of data.

+

int32_t BulkReadData(const UsbDev &dev, const UsbPipe &pipe, std::vector &data);

+

Obtains the data reading result. Use this method together with BulkReadData. +

int32_t BulkWriteData(const UsbDev &dev, const UsbPipe &pipe, const std::vector &data);

+

Writes bulk data in isochronous manner. This method is applicable to transfer of a huge amount of data.

+

int32_t BulkGetWriteCompleteLength(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length);

+

Obtains the data writing status based on length. Use this method together with BulkWriteData.

+
+ +- ### Device + + + + + + + + + + + + + + + + + + + + + +

Header File

+

API

+

Description

+

usb_srv_client.h

+

+

+

int32_t GetCurrentFunctions(int32_t &funcs);

+

Obtains the numeric mask combination for the current USB function list in Device mode.

+

int32_t SetCurrentFunctions(int32_t funcs);

+

Sets the current USB function list in Device mode.

+

int32_t UsbFunctionsFromString(std::string funcs);

+

Converts the string descriptor of a given USB function list to a numeric mask combination.

+

std::string UsbFunctionsToString(int32_t funcs);

+

Converts the numeric mask combination of a given USB function list to a string descriptor.

+
+ +- ### Port + + + + + + + + + + + + + + + + + + +

Header File

+

API

+

Description

+

usb_srv_client.h

+

+

+

int32_t GetSupportedModes(int32_t portId, int32_t &supportedModes);

+

Obtains the mask combination for the supported mode list of a given port.

+

int32_t SetPortRole(int32_t portId, int32_t powerRole, int32_t dataRole);

+

Sets the role types supported by a specified port, which can be powerRole (for charging) or dataRole (for data transfer).

+

int32_t GetPorts(std::vector &usbPorts);

+

Obtains the USB port descriptor list.

+
diff --git a/en/device-dev/subsystems/subsys-usbservice.md b/en/device-dev/subsystems/subsys-usbservice.md new file mode 100644 index 0000000000000000000000000000000000000000..369a182c4f3507d622b2759f0bf2429d9f50244f --- /dev/null +++ b/en/device-dev/subsystems/subsys-usbservice.md @@ -0,0 +1,7 @@ +# USB + +- **[USB Overview](subsys-usbservice-overview.md)** + +- **[USB Usage Guidelines](subsys-usbservice-guide.md)** + +- **[USB Usage Example](subsys-usbservice-demo.md)** \ No newline at end of file