diff --git a/en/device-dev/subsystems/subsys-toolchain.md b/en/device-dev/subsystems/subsys-toolchain.md index 193fb093ce8836530a90726e93a5c7aa1a226ce6..baceec80d1887fd681d94908a126adeb34706aca 100644 --- a/en/device-dev/subsystems/subsys-toolchain.md +++ b/en/device-dev/subsystems/subsys-toolchain.md @@ -2,6 +2,6 @@ - **[bytrace Usage Guidelines](subsys-toolchain-bytrace-guide.md)** -- **[hdc\_std Usage Guidelines](oem_subsys_toolchain_hdc_guide.md)** +- **[hdc\_std Usage Guidelines](subsys_toolchain_hdc_guide.md)** diff --git a/en/device-dev/subsystems/subsys-utils.md b/en/device-dev/subsystems/subsys-utils.md index 53ee39995f7021e3f563ee7cc6ceb08a2353f247..d9da7eb8e4903fcaeae188a8f45367037d9a848c 100644 --- a/en/device-dev/subsystems/subsys-utils.md +++ b/en/device-dev/subsystems/subsys-utils.md @@ -1,9 +1,9 @@ # Utils -- **[Utils Overview](oem_subsys_utils_des.md)** +- **[Utils Overview](subsys_utils_overview.md)** -- **[Utils Development Guidelines](oem_subsys_utils_guide.md)** +- **[Utils Development Guidelines](subsys_utils_guide.md)** -- **[Utils FAQ](oem_subsys_utils_faq.md)** +- **[Utils FAQ](subsys_utils_faqs.md)** diff --git a/en/device-dev/subsystems/subsys_utils_faqs.md b/en/device-dev/subsystems/subsys_utils_faqs.md new file mode 100644 index 0000000000000000000000000000000000000000..0f1ed0e9f06e62e99e05c81ea78333f80bffd007 --- /dev/null +++ b/en/device-dev/subsystems/subsys_utils_faqs.md @@ -0,0 +1,20 @@ +# Utils FAQ + +## 1. Failure in running the KV store on the LiteOS Cortex-A kernel \(Hi3516 or Hi3518\) due to incorrect path setting for the KV store + +**Problem** + +When the LiteOS Cortex-A kernel \(Hi3516 or Hi3518 platform\) directly calls the API provided by the KV store, the compiled executable program fails to run. + +**Possible Causes** + +The compiled executable program is run directly without being converted to an application using **AbilityKit** APIs. In this case, the Bundle Manager Service \(BMS\) cannot correctly set the path for storing application data during application installation. As a result, the KV store fails to run. + +**Solution** + +Call the **UtilsSetEnv** function of the KV store to set the data storage path. + +``` +UtilsSetEnv("/storage/com.huawei.kv"); +``` + diff --git a/en/device-dev/subsystems/subsys_utils_guide.md b/en/device-dev/subsystems/subsys_utils_guide.md new file mode 100644 index 0000000000000000000000000000000000000000..1988c6b9c43fb96ab6cd04a24fb5148dc8a3648e --- /dev/null +++ b/en/device-dev/subsystems/subsys_utils_guide.md @@ -0,0 +1,284 @@ +# Utils Development Guidelines + +## Available APIs + +**Table 1** APIs for file operations + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Function

+

Description

+

int UtilsFileOpen(const char* path, int oflag, int mode)

+

Opens or creates a file.

+

int UtilsFileClose(int fd)

+

Closes a file with a specified file descriptor.

+

int UtilsFileRead(int fd, char *buf, unsigned int len)

+

Reads a specified length of data from a file with the specified file descriptor and writes the data into the buffer.

+

int UtilsFileWrite(int fd, const char *buf, unsigned int len)

+

Writes a specified length of data into a file with the specified file descriptor.

+

int UtilsFileDelete(const char *path)

+

Deletes a specified file.

+

int UtilsFileStat(const char *path, unsigned int *fileSize)

+

Obtains the file size.

+

int UtilsFileSeek(int fd, int offset, unsigned int whence)

+

Adjusts the read and write position offset in a file.

+

int UtilsFileCopy(const char* src, const char* dest)

+

Copies the source file to a target file.

+

int UtilsFileMove(const char* src, const char* dest)

+

Moves the source file into a target file.

+
+ +Sample code for file operations: + +``` +// Open a file and write data. +char fileName[] = "testfile"; +static const char def[] = "utils_file_operation implement."; +int fd = UtilsFileOpen(fileName, O_RDWR_FS | O_CREAT_FS | O_TRUNC_FS, 0); +printf("file handle = %d\n", fd); +int ret = UtilsFileWrite(fd, def, strlen(def)); +printf("write ret = %d\n", ret); + +// Adjust the position offset in the file. +ret = UtilsFileSeek(fd, 5, SEEK_SET_FS); +printf("lseek ret = %d\n", ret); + +// Read data and close the file. +char buf[64] = {0}; +int readLen = UtilsFileRead(fd, buf, 64); +ret = UtilsFileClose(fd); +printf("read len = %d : buf = %s\n", readLen, buf); + +// Obtain the file size. +int fileLen = 0; +ret = UtilsFileStat(fileName, &fileLen); +printf("file size = %d\n", fileLen); + +// Delete the file. +ret = UtilsFileDelete(fileName); +printf("delete ret = %d\n", ret); +``` + +**Table 2** APIs for KV store operations + + + + + + + + + + + + + + + + +

Function

+

Description

+

int UtilsGetValue(const char* key, char* value, unsigned int len)

+

Obtains the value matching a specified key from the file system or cache.

+

int UtilsSetValue(const char* key, const char* value)

+

Adds or updates the value matching a specified key in the file system or cache.

+

int UtilsDeleteValue(const char* key)

+

Deletes the value matching a specified key from the file system or cache.

+
+ +Sample code for the KV store: + +``` +// Set the value matching the specified key. +char key[] = "rw.sys.version_100"; +char value[] = "Hello kv operation implement!"; +int ret = UtilsSetValue(key, value); +printf("UtilsSetValue set ret = %d\n", ret); + +// Obtain the value matching the specified key. +char temp[128] = {0}; +ret = UtilsGetValue(key, temp, 128); +printf("UtilsGetValue get ret = %d, temp = %s\n", ret, temp); + +// Delete the value matching the specified key. +ret = UtilsDeleteValue(key); +printf("UtilsDeleteValue delete ret = %d\n", ret); +``` + +## How to Develop + +### Developing a Native Application for the KV Store That Uses the LiteOS Cortex-A Kernel \(Hi3516 or Hi3518\) + +1. Develop the native application for the KV store using **AbilityKit** APIs. + - Write the user program by calling the APIs provided by the KV store and compile the **libLauncher.so** file. + + ``` + // Set the value matching the specified key. + char key[] = "rw.sys.version_100"; + char value[] = "Hello kv operation implement!"; + int ret = UtilsSetValue(key, value); + printf("UtilsSetValue set ret = %d\n", ret); + + // Obtain the value matching the specified key. + char temp[128] = {0}; + ret = UtilsGetValue(key, temp, 128); + printf("UtilsGetValue get ret = %d, temp = %s\n", ret, temp); + + // Delete the value matching the specified key. + ret = UtilsDeleteValue(key); + printf("UtilsDeleteValue delete ret = %d\n", ret); + ``` + + - Edit the **config.json** file as follows: + + ``` + { + "app": { + "bundleName": "com.huawei.launcher", + "vendor": "huawei", + "version": { + "code": 1, + "name": "1.0" + } + }, + "deviceConfig": { + "default": { + "reqSdk": { + "compatible": "zsdk 1.0.0", + "target": "zsdk 1.0.1" + }, + "keepAlive": false + }, + "smartCamera": { + "reqSdk": { + "compatible": "zsdk 1.0.0", + "target": "zsdk 1.0.1" + }, + "keepAlive": false + } + }, + "module": { + "package": "com.huawei.launcher", + "name": ".MyHarmonyAbilityPackage", + "deviceType": [ + "phone", "tv","tablet", "pc","car","smartWatch","sportsWatch","smartCamera" + ], + "distro": { + "deliveryWithInstall": true, + "moduleName": "Launcher", + "moduleType": "entry" + }, + "abilities": [{ + "name": "MainAbility", + "icon": "res/drawable/phone.png", + "label": "test app 1", + "launchType": "standard", + "type": "page" + }, + { + "name": "SecondAbility", + "icon": "res/drawable/phone.png", + "label": "test app 2", + "launchType": "standard", + "type": "page" + }, + { + "name": "ServiceAbility", + "icon": "res/drawable/phone.png", + "label": "test app 2", + "launchType": "standard", + "type": "service" + } + ] + } + } + ``` + + - Generate a HAP file. + + - Add resource files in the **res/drawable** directory based on the following directory structure. + + ![](figure/unnaming.png) + + - Compress the **libLauncher.so**, **config.json**, and resource files into a ZIP package and change the file name extension to **.hap**, for example, **Launcher.hap**. + +2. Connect the development board and send the command for installing the native KV store application to the board through the serial port. + + ``` + ./nfs/dev_tools/bin/bm install -p /nfs/Launcher.hap + ``` + +3. Send the command for running the native KV store application to the board through the serial port. + + ``` + ./nfs/dev_tools/bin/aa start -p com.huawei.launcher -n ServiceAbility + ``` + + +### Dumping System Attributes on the Platform That Uses the LiteOS Cortex-M Kernel + +1. Connect the development board and send the **AT+SYSPARA** command to the board through the serial port. + + ``` + AT+SYSPARA + ``` + + **Figure 1** Output of the system attribute dumping command for the LiteOS Cortex-M kernel + ![](figure/output-of-the-system-attribute-dumping-command-for-the-liteos-cortex-m-kernel.png "output-of-the-system-attribute-dumping-command-for-the-liteos-cortex-m-kernel") + + +### Dumping System Attributes on the Platform That Uses the LiteOS Cortex-A Kernel + +1. Connect the development board and run the **os\_dump --help** command in the **bin** directory to view the **os\_dump** help information. + + ``` + ./bin/os_dump --help + ``` + +2. Run the **os\_dump -l** command in the **bin** directory to view system modules that support attribute dumping. + + ``` + ./bin/os_dump -l + ``` + +3. Run the **os\_dump syspara** command in the **bin** directory to dump the current system attributes. + + ``` + ./bin/os_dump syspara + ``` + + **Figure 2** Output of the system attribute dumping command for the LiteOS Cortex-A kernel + ![](figure/output-of-the-system-attribute-dumping-command-for-the-liteos-cortex-a-kernel.png "output-of-the-system-attribute-dumping-command-for-the-liteos-cortex-a-kernel") + + diff --git a/en/device-dev/subsystems/subsys_utils_overview.md b/en/device-dev/subsystems/subsys_utils_overview.md new file mode 100644 index 0000000000000000000000000000000000000000..a4fce877812cad2542a191bf2bcd6335a93084ef --- /dev/null +++ b/en/device-dev/subsystems/subsys_utils_overview.md @@ -0,0 +1,10 @@ +# Utils Overview + +The Utils library stores common basic components of OpenHarmony. These basic components can be used by OpenHarmony service subsystems and upper-layer applications. + +The Utils library provides the following capabilities on different platforms: + +LiteOS Cortex-M \(Hi3861 platform\): KV store, file operations, IoT peripheral control, and system attribute dumping + +LiteOS Cortex-A \(Hi3516 or Hi3518 platform\): KV store, timer, JavaScript APIs for data and file storage, and system attribute dumping + diff --git a/zh-cn/device-dev/quick-start/quickstart-lite-steps-hi3816-running.md b/zh-cn/device-dev/quick-start/quickstart-lite-steps-hi3861-running.md similarity index 100% rename from zh-cn/device-dev/quick-start/quickstart-lite-steps-hi3816-running.md rename to zh-cn/device-dev/quick-start/quickstart-lite-steps-hi3861-running.md diff --git a/zh-cn/device-dev/quick-start/quickstart-lite-steps-hi3861.md b/zh-cn/device-dev/quick-start/quickstart-lite-steps-hi3861.md index 21059f2437a3bd439d40db4779330011e90c9988..7d6e71a329f877022e8b3ce559ff25c09aa18a06 100644 --- a/zh-cn/device-dev/quick-start/quickstart-lite-steps-hi3861.md +++ b/zh-cn/device-dev/quick-start/quickstart-lite-steps-hi3861.md @@ -10,7 +10,7 @@ - **[调试验证](quickstart-lite-steps-hi3861-debug.md)** -- **[运行](quickstart-lite-steps-hi3816-running.md)** +- **[运行](quickstart-lite-steps-hi3861-running.md)** - **[常见问题](quickstart-lite-steps-hi3861-faqs.md)** diff --git a/zh-cn/device-dev/subsystems/subsys_toolchain_hdc_guide.md b/zh-cn/device-dev/subsystems/subsys_toolchain_hdc_guide.md new file mode 100644 index 0000000000000000000000000000000000000000..3c72f79eac135f35b8e2a125cd3ede923fc3db05 --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys_toolchain_hdc_guide.md @@ -0,0 +1,667 @@ +# hdc\_std Usage Guidelines + +hdc\_std \(OpenHarmony Device Connector\) is a command line tool provided by OpenHarmony for debugging. With this tool, you can interact with real devices or simulators from a Windows or Linux OS. + +This section describes how to set up the hdc\_std environment and use its common commands. + +## Preparations + +**Obtaining hdc\_std:** + +Obtain **hdc\_std** from the **prebuilt** directory at [developtools\_hdc\_standard](https://gitee.com/openharmony/developtools_hdc_standard). + +**Example:** + +To obtain hdc\_std on Windows, obtain the executable file **hdc\_std.exe** from **prebuilt/windows** and place it in a directory on the disk. + +## Important Notes + +- If an exception occurs when you are using hdc\_std, run the **hdc\_std kill** command to kill the hdc\_std service or run the **hdc\_std start -r** command to restart the service process. +- If no device information is obtained after **hdc\_std list targets** is executed, use the task manager to check whether the **hdc.exe** process exists. If it exists, kill the process. + +## Option-related Commands + +The following commands are available: + +### -h/help -v/version + +Obtains hdc help and version information. + +**Table 1** Command description + + + + + + + + + +

Return Value

+

Description

+

Required information

+

hdc help or version information

+
+ +Examples: + +hdc\_std -h / hdc\_std help + +hdc\_std -v / hdc\_std version + +### -t key + +Connects to a device with a specified key. + +**Table 2** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

key

+

Key that identifies the device. The value is in the IP address:Port number format or is a USB serial number.

+

Return Value

+

Description

+

1. error: device '***' not found

+

②Nothing to do...

+

1. The device does not exist.

+

2. The command appended to -t key does not exist.

+
+ +Examples: + +This option must be used together with a specific operation command. The following uses the shell command as an example: + +**hdc\_std list targets** \(obtain device information\) + +**hdc\_std -t _key_ shell** \(replace _key_ with the device information obtained\) + +>![](../public_sys-resources/icon-note.gif) **NOTE:** +>You can connect to multiple devices from the device you use for development. Each device has a unique key. The key can be _IP address:Port number_ for a device connected through a network or the serial number for a device connected through USB. + +## Querying the Device List + +The following command is used to query the device list: + +### list targets\[-v\] + +Displays all the connected devices. + +**Table 3** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

-v

+

Prints detailed device information.

+

Return Value

+

Description

+

1. Device information

+

②[Empty]

+

1. A list of connected devices

+

2. No device information is found.

+
+ +Examples: + +hdc\_std list targets + +hdc\_std list targets -v + +## Service Process Commands + +The following commands are available: + +### target mount + +Mounts a partition, such as **/system**, with the read and write permissions. + +**Table 4** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

None

+

None

+

Return Value

+

Description

+

①Mount finish

+

2. Returned information

+

1. Information returned when the operation is successful.

+

2. Information returned when the operation fails.

+
+ +Example: + +hdc\_std target mount + +### smode \[off\] + +Grants the root permission to a background service process. The **off** option is used to revoke the granted permission. + +Examples: + +hdc\_std smode + +hdc\_std smode off + +### kill \[-r\] + +Stops a service process. + +**Table 5** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

-r

+

Triggers the service restart.

+

Return Value

+

Description

+

①Kill server finish

+

2. Error information

+

1. Information returned when the operation is successful.

+

2. The operation fails.

+
+ +Example: + +hdc\_std kill + +### start \[-r\] + +Starts a service process. + +**Table 6** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

-r

+

Restarts the service process if it has started.

+

Return Value

+

Description

+

None

+

None

+
+ +Examples: + +hdc\_std start + +## Network Commands + +The following commands are available: + +### tconn _host_\[:_port_\]\[-remove\] + +Connects to a device with a specified IP address and port number. + +**Table 7** Command description + + + + + + + + + + + + + + + + + + +

Parameter

+

Description

+

host[:port]

+

IP address and port number of the device to be connected

+

-remove

+

Disconnects from the specified device.

+

Return Value

+

Description

+

1. Error information

+

2. None

+

1. The operation fails.

+

2. The operation is successful.

+
+ +Example: + +hdc\_std tconn 192.168.0.100:8710 + +### tmode usb + +Restarts the daemon process and connects to the device using USB. + +**Table 8** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

None

+

None

+

Return Value

+

Description

+

1. Error information

+

2. None

+

1. The operation fails.

+

2. The operation is successful.

+
+ +Example: + +hdc\_std tmode usb + +### tmode port _port-number_ + +Restarts the daemon process and connects to the device over TCP. + +**Table 9** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

port-number

+

Port number used to connect to the device

+

Return Value

+

Description

+

1. Error information

+

2. None

+

1. The operation fails.

+

2. The operation is successful.

+
+ +Example: + +hdc\_std tmode port 8710 + +>![](../public_sys-resources/icon-note.gif) **NOTE:** +>After this command is executed, the remote daemon process exits and restarts, and the TCP connection is enabled by default. If you do not include **port-number** in this command, a random port will be used to connect to the device. + +## File Commands + +The following commands are available: + +### file send _local remote_ + +Sends a file to a remote device. + +**Table 10** Command description + + + + + + + + + + + + + + + + + + +

Parameter

+

Description

+

local

+

Path of the file to send

+

remote

+

Destination path on the remote device

+

Return Value

+

Description

+

1. Error information

+

2. File transfer result

+

1. The operation fails.

+

2. The operation is successful.

+
+ +Example: + +hdc\_std file send E:\\a.txt /data/local/tmp/a.txt + +### file recv \[-a\] _remote local_ + +Receives a file from a remote device. + +**Table 11** Command description + + + + + + + + + + + + + + + + + + + + + +

Parameter

+

Description

+

-a

+

File retention timestamp mode

+

local

+

Path on the local device to receive the file

+

remote

+

File path on the remote device

+

Return Value

+

Description

+

1. Error information

+

2. None

+

1. The operation fails.

+

2. The operation is successful.

+
+ +Example: + +hdc\_std file recv /data/local/tmp/a.txt ./a.txt + +## App Commands + +The following commands are available: + +### install \[-r/-d/-g\] _package_ + +Installs the OpenHarmony application. + +**Table 12** Command description + + + + + + + + + + + + + + + + + + + + + + + + +

Parameter

+

Description

+

package

+

OpenHarmony application installation package

+

-r

+

Replaces an existing application.

+

-d

+

Allows downgraded installation.

+

-g

+

Grants permission dynamically

+

Return Value

+

Description

+

1. Error information

+

2. None

+

1. The operation fails.

+

2. The operation is successful.

+
+ +Example: + +hdc\_std install _hwadmin.hap_ + +### uninstall \[-k\] _package_ + +Uninstalls the OpenHarmony application. + +**Table 13** Command description + + + + + + + + + + + + + + + + + + +

Parameter

+

Description

+

package

+

OpenHarmony application installation package

+

-k

+

Retains /data/cache.

+

Return Value

+

Description

+

1. Error information

+

2. None

+

1. The operation fails.

+

2. The operation is successful.

+
+ +Example: + +hdc\_std uninstall _package_ + +## Debugging Commands + +The following commands are available: + +### hilog + +Obtains logs for debugging. + +**Table 14** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

None

+

None

+

Return Value

+

Description

+

Returned information

+

Obtained logs

+
+ +Example: + +hdc\_std hilog + +### shell \[_command_\] + +Executes a command remotely or enters an interactive command environment. + +**Table 15** Command description + + + + + + + + + + + + + + + +

Parameter

+

Description

+

command

+

Command to be executed

+

Return Value

+

Description

+

Returned information

+

Execution result of the command

+
+ +Examples: + +hdc\_std shell + +## Troubleshooting + +### hdc\_std Fails to Connect to a Device + +- **Symptom** + + **\[Empty\]** is displayed in the output after the **hdc\_std list targets** command is executed. + +- **Solutions** + 1. The device cannot be identified. + + Check whether **HDC Device** exists in the universal serial bus device of the device manager. If **HDC Device** does not exist, the device cannot be connected. In this case, remove and then insert the device or burn the latest image for the device. + + 2. hdc\_std works improperly. + + Run the **hdc kill** or **hdc start -r** command to kill or restart the hdc service. Then, run the **hdc list targets** command to check whether device information can be obtained. + + 3. hdc\_std does not match the device. + + If the latest image is burnt on the device, the latest hdc\_std version must be used. As hdc\_std is updated continuously, obtain hdc\_std of the latest version from the **developtools\_hdc\_standard** repository in the **prebuilt** directory. + + + +## hdc\_std Fails to Run + +- **Symptom** + + The **hdc\_std.exe** file does not run after being clicked. + +- **Solutions** + + **hdc\_std.exe** requires no installation. It can be directly used on a disk or added to environment variables. Open the cmd window and run the **hdc\_std** command to use **hdc\_std.exe**.