前言

此文档用于指导开发者从OpenHarmony简介、环境搭建、创建第一个OpenHarmony项目等方面初步了解OpenHarmony应用开发的流程。

OpenHarmony简介

OpenHarmony是由开放原子开源基金会(OpenAtom Foundation)孵化及运营的开源项目,目标是面向全场景、全连接、全智能时代、基于开源的方式,搭建一个智能终端设备操作系统的框架和平台,促进万物互联产业的繁荣发展。

官网地址:https://www.openharmony.cn

码云仓库地址:https://gitee.com/openharmony

工具简介

DevEco Studio是OpenHarmony应用开发推荐的IDE工具。HUAWEI DevEco Studio For OpenHarmony是基于IntelliJ IDEA Community开源版本打造,面向OpenHarmony全场景多设备的一站式集成开发环境(IDE),为开发者提供工程模板创建、开发、编译、调试、发布等E2E的OpenHarmony应用/服务开发。通过使用DevEco Studio,开发者可以更高效的开发具备OpenHarmony分布式能力的应用/服务,进而提升创新效率。

下载地址: https://developer.harmonyos.com/cn/develop/deveco-studio#download_beta_openharmony

下载版本: DevEco Studio 3.0 Release

Download IDE

 

环境搭建

下载安装Dev Eco Studio

工具简介里通过下载地址下载对应的DevEco Studio,下载完成后进行安装,安装时不需要特殊配置,选择接受和默认配置就能安装成功。

nodejs环境变量配置

由于DevEco Studio自带nodejs,因此我们不需要单独下载nodejs,只需要配置环境变量即可。

1.右键此电脑->属性->高级系统设置->环境变量,查看用户变量下是否存在Path变量,如果不存在,点击新建按钮,新建一个变量名Path变量值DevEco Studio下所自带的nodejs路径(比如D:\DevEcoStudio\tools\nodejs)。

setup nodejs

 

2.配置完成后,打开cmd,输入命令node -v查看版本号,显示版本号则表示nodejs环境变量配置成功。

nodejs version

 

DevEco Studio配置

打开DevEco Studio,进入主界面,依次点击Configure->Settings->OpenHarmony SDK,将API Version9全部勾选,点击Apply依次按照步骤下载SDK,下载完成后点击OK。

至此整个开发环境安装配置基本完成,其中对于一些个性化设置可以搜索网上的文章自行配置。

创建第一个OpenHarmony项目

创建工程

1. 选择模板

打开DevEco Studio,选择Create Project进入Choose your ability template,选择OpenHarmony 下的Empty Ability模板。 DevEco Studio提供了两类Template(HarmonyOs和OpenHarmony),每个模板都有符合自己应用的场景,其中Empty Ability是默认创建的ets工程模板。

create1

 

create2

 

2. 填写项目信息

Project name:项目名称,全英文

Project type:项目类型,默认选择Application

Bundle name:包名,修改为自己需要的包名

Save location:项目路径,必须为空文件夹,建议项目路径不包含中文字符

Compile SDK:SDK版本,选择9

Model:开发模型,SDK选9时默认为Stage

Enable Super Visual:是否开启低代码开发,默认不选择

Language:开发语言,API选9时仅有eTS

Compatible SDK:兼容SDK,选择9

Device Type:设备类型,默认全部勾选

Show in service center:默认不选择

create3

 

3. 下载资源

项目生成后会自动通过npm下载一些资源,下载完成并构建成功后可手动打开index.ets。

create4

 

4. 代码编写

将index.ets里的

@State message: string = 'Hello World'

改为

@State message: string = 'Hello OpenHarmony'

create5

 

5. 预览界面

打开./entry/src/main/ets/pages/index.ets,然后单击右侧的Previewer按钮即可预览到界面显示"Hello OpenHarmony"。

create6

 

6. debug模式

在编辑窗口右上角的工具栏,点击三角形样式的按钮运行,等待编译完成即可便运行在设备上。如果想要进行断点调试,则在想要调试的代码行打上断点,并点击甲虫样式的按钮运行。调试模式需要配置签名。

create7

 

项目打包和配置签名

1. 打包

项目需要打包的时候选择菜单Build->Build Hap(s)/App(s)->Build Hap(s),打包成功后会生成1个build文件夹。打开项目entry目录下的build->default->outputs->default文件夹,entry-default-unsigned.hap就是打包后的应用,这里面unsigend就表明这是一个未签名的应用包,未签名的hap包是无法安装到开发板上的。

sign1

 

sign2

 

2. 配置签名

DevEco Studio目前支持2种签名,手动签名和自动签名,可以根据自己的使用习惯去选择签名方式。

2.1 手动签名

手动签名可以使用OpenHarmony内置的密钥库文件OpenHarmony.p12,内含根CA证书、中间CA证书、最终实体证书等信息,也可以所有签名相关的文件都自定义生成(由于自定义签名流程较为复杂,故不在此详述)。

DevEco Studio签名方式发生了改变,需要用到Sdk/Toolchains/lib里的相关文件,参照2.1.2注意事项,故在项目根目录下创建一个keys文件夹,将签名需要用到的文件都放在该目录下,并且后续指令默认cd到keys路径下调用。

2.1.1 命令行签名
  • 生成应用签名证书密钥对 

    执行以下指令

java -jar hap-sign-tool.jar generate-keypair -keyAlias "OpenHarmony Personal Application Release" -keyAlg "ECC"  -keySize "NIST-P-256" -keystoreFile OpenHarmony.p12 -keyPwd "123456" -keystorePwd "123456"

当前目录下的OpenHarmony.p12会生成别名为OpenHarmony Personal Application Release的密钥对。

参数含义:

generate-keypair:生成密钥对和密钥库文件指令。

-keyAlias:密钥别名,必填项。可自定义。

-keyPwd:密钥口令,可选项。可自定义。

-keyAlg:密钥算法,必填项。包括RSA/ECC。默认填写ECC。

-keySize:密钥长度,必填项,RSA算法的长度为2048/3072/4096,ECC算法的长度NIST-P-256/NIST-P-384。默认填写NIST-P-256。

-keystoreFile:密钥库文件,必填项,JKS或P12格式。默认使用OpenHarmony.p12。

-keystorePwd:密钥库口令,可选项。默认填写123456。

  • 生成应用签名证书

    执行以下指令

java -jar hap-sign-tool.jar generate-app-cert -keyAlias "OpenHarmony Personal Application Release" -signAlg "SHA256withECDSA"  -issuer "C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN= OpenHarmony Application CA" -issuerKeyAlias "openharmony application ca" -subject "C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN=OpenHarmony Application Release" -keystoreFile OpenHarmony.p12 -subCaCertFile subCA.cer -rootCaCertFile rootCA.cer -outForm "certChain" -outFile PersonalApplication.cer -keyPwd "123456" -keystorePwd "123456" -issuerKeyPwd "123456" -validity "3650"

当前目录下会生成PersonalApplication.cer应用签名证书。

参数含义:

generate-app-cert:生成应用调试/发布证书指令。

-keyAlias:密钥别名,必填项。使用2.2.1定义的别名。

-keyPwd:密钥口令,可选项。使用2.2.1定义的口令。

-issuer:颁发者的主题,必填项。默认填写C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN= OpenHarmony Application CA。

-issuerKeyAlias:颁发者的密钥别名,必填项。默认填写openharmony application ca。

-issuerKeyPwd:颁发者的密钥口令,可选项。默认填写123456。

-subject:证书主题,必填项。默认填写C=CN,O=OpenHarmony,OU=OpenHarmony Team,CN=OpenHarmony Application Release。

-validity:证书有效期,可选项。默认填写3650天。

-signAlg:签名算法,必填项,包括SHA256withECDSA / SHA384withECDSA。默认填写 SHA256withECDSA。

-keystoreFile:钥库文件,必填项,JKS或P12格式。默认使用OpenHarmony.p12。

-keystorePwd:密钥库口令,可选项。使用填写123456。

-outForm:输出证书文件的格式,包括 cert / certChain,可选项。默认填写certChain。

-rootCaCertFile:outForm为certChain时必填,根CA证书文件。默认使用subCA.cer。

-subCaCertFile:outForm为certChain时必填,中间CA证书文件。默认使用rootCA.cer。

-outFile:输出证书文件(证书或证书链),可选项,如果不填,则直接输出到控制台。可自定义。

  • 对profile文件进行签名

    修改UnsgnedReleasedProfileTemplate.json里的bundle-name为自己待签名hap的包名。执行以下指令

java -jar hap-sign-tool.jar sign-profile -keyAlias "openharmony application profile release" -signAlg "SHA256withECDSA" -mode "localSign" -profileCertFile OpenHarmonyProfileRelease.pem -inFile UnsgnedReleasedProfileTemplate.json -keystoreFile OpenHarmony.p12 -outFile PersonalProfile.p7b -keyPwd "123456" -keystorePwd "123456"

当前目录下会生成PersonalProfile.p7b profile签名文件。

参数含义:

sign-profile:ProvisionProfile文件签名指令。

-mode:签名模式,必填项,包括localSign,remoteSign。默认填写localSign。

-keyAlias:密钥别名,必填项。默认填写openharmony application profile release。

-keyPwd:密钥口令,可选项。默认填写123456。

-profileCertFile:Profile签名证书(证书链,顺序为最终实体证书-中间CA证书-根证书),必填项。默认 使用OpenHarmonyProfileRelease.pem。

-inFile:输入原始的模板Profile文件,文件为json格式,必填项。

-signAlg:签名算法,必填项,包括SHA256withECDSA / SHA384withECDSA。默认填写 SHA256withECDSA。

-keystoreFile:钥库文件,必填项,JKS或P12格式。默认使用OpenHarmony.p12。

-keystorePwd:密钥库口令,可选项。默认填写123456。

-outFile:输出签名后的Provision Profile文件,p7b格式,必填项。可自定义。

  • 对Hap包进行签名

    执行以下指令

java -jar hap-sign-tool.jar sign-app -keyAlias "OpenHarmony Personal Application Release" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile PersonalApplication.cer -profileFile PersonalProfile.p7b -inFile unsignApp.hap -keystoreFile OpenHarmony.p12 -outFile signApp.hap -keyPwd "123456" -keystorePwd "123456"

当前目录下会创建signApp.hap已经签名完成的hap包。

参数含义:

sign-app:hap应用包签名指令。

-mode:签名模式,必填项,包括localSign,remoteSign,remoteResign。默认填写localSign。

-keyAlias:密钥别名,必填项。使用2.1.1.1定义的别名。

-keyPwd:密钥口令,可选项。使用2.1.1.1定义的口令。

-appCertFile:应用签名证书文件(证书链,顺序为最终实体证书-中间CA证书-根证书),必填项。使用 2.1.1.2创建的文件。

-profileFile:签名后的Provision Profile文件名,p7b格式,必填项。使用2.1.1.3创建的文件。

-inFile:输入的原始APP包文件,hap格式或bin格式,必填项。

-signAlg:签名算法,必填项,包括SHA256withECDSA / SHA384withECDSA。默认填写 SHA256withECDSA。

-keystoreFile:密钥库文件,localSign模式时为必填项,JKS或P12格式。默认使用OpenHarmony.p12。

-keystorePwd:密钥库口令,可选项。默认填写123456。

-outFile:输出签名后的包文件,必填项。

2.1.2 注意事项
  • 生成应用签名证书密钥对步骤中的密钥对算法推荐使用ECC,出于安全性考虑,应用签名暂不使用RSA算法。

  • 建议将待签名hap包、profile原始模板文件、密钥库文件OpenHarmony.p12、根CA证书、中间CA证书、签名工具放在同一个目录下,方便操作。 在码云OpenHarmony/developtools_hapsigner/autosign/result路径下,有如下文件:

    • OpenHarmony密钥库文件OpenHarmony.p12

    • 根CA证书rootCA.cer

    • 中间CA证书subCA.cer

    • profile签名证书OpenHarmonyProfileRelease.pem

    在本地sdk/toolchains/lib路径下,有如下文件:

    • UnsgnedReleasedProfileTemplate.json

2.1.3 IDE签名

IDE签名跟命令行签名前三个步骤相同,区别在于第四步对hap包签名时,IDE需要在File->Project Struture->Project->default->Signing Configs下手动配置相关的签名文件和签名信息,然后通过Build->Build Hap(s)/App(s)->Build Hap(s)去生成签名hap包。

2.2 自动签名
  • 配置自动签名

    选择菜单依次点击File->Project Struture->Project->default->Signing Configs,勾选上Automatically generate signing,点击Apply,可以发现在根目录的build-profile.json5中已经生成了signingConfigs签名配置。

    sign3

     

    sign4

     

  • 应用签名打包

    选择菜单依次点击Build->Build Hap(s)/App(s)->Build Hap(s),待控制台日志显示打包签名成功可以发现entry/build/default/outputs/default下面多出了一个文件entry-default-signed.hap,这个文件就是经过签名后的hap包。

    sign5

     

应用安装

OpenHarmony应用安装有多种方式,如USB安装、串口安装、镜像烧录等,以下会以应用开发常见安装方式USB安装为目标来介绍。

1. 连接设备

1.1 查看驱动

将设备连接至pc后,在设备管理器或者设备与打印机中查看是否有hdc设备,如下图所示:

设备与打印机

 

设备管理器

 

一般来说Windows10都能正确的识别搭载OpenHarmony的设备。

1.2 重载或重装驱动

如果设备接入后识别不到HDC设备,可以按照如下步骤尝试重载或者重装驱动。

1.2.1 重载

下载这个工具,在目标设备上右键restart device。

usbtreeview

 

同理也可以尝试重启下根集线器(比较危险,说不准出问题,要重启PC才能恢复)。

1.2.2 重装

下载并打开Zadig,插入设备,Options里面打开List All Devices,下拉框找到HDC Device,然后点击Reinstall Driver。

zadig

 

2. 获取HDC

HDC(OpenHarmony Device Connector) 是为开发人员提供的用于设备连接调试的命令行工具,pc端开发机使用命令行工具hdc_std,该工具需支持部署在Windows/Linux/Mac等系统上与OpenHarmony设备(或模拟器)进行连接调试通信。

搭载HarmonyOS与OpenHarmony的设备或模拟器使用的HDC版本是不一样的,不能混用。适配HarmonyOS的HDC一般命名为hdc.exe,OpenHarmony的HDC一般则为hdc_std.exe

OpenHarmony HDC工具仓库地址:https://gitee.com/openharmony/developtools_hdc_standard

2.1 SDK内获取

在DevEco中下载了OpenHarmony SDK后,可以在SDK路径下的toolchains文件内找到hdc_std.exe

2.2 源码编译获取

sdk源码编译比较复杂,这里不多做介绍,可以参考https://gitee.com/openharmony/build/blob/master/README_zh.mdhdc_std.exe会被编译打包到里面。

2.3 DailyBuilds下载

DailyBuilds上下载最新,或者其他日期的ohos-sdk包,hdc_std.exe位于windows下toolchains压缩包内。

DailyBuilds

 

3. 使用HDC

hdc_std.exe无法直接双击运行,需要在windows的cmd工具中运行。

3.1 打开cmd

打开命令提示符工具,cd到hdc_std.exe所在目录,也可以将该目录加入环境变量中,这样不用每次切换到该目录就可以运行hdc命令。

3.2 查看已连接的设备

输入命令hdc_std list targets -v

targets

 

其中第一串数字应该与设备OpenHarmony中设置-关于手机-设备中的编号保持一致。如果设备未显示Connected,可以重启设备再试。

3.3 安装HAP包至设备内

输入命令hdc_std install D:\\HelloOpenHarmony.hap,安装成功会提示msg:install bundle successfully.,接着就能在设备的launcher界面中找到该应用的图标。

如果提示:

msg:error: failed to install bundle. error: install entry already exist.

则需要先使用hdc_std uninstall bundleName卸载已安装的hap包。bundleName在工程AppScope/app.json5文件中查看。

4. HDC问题排查

有些时候,我们可以通过list targets命令查看到设备,并且显示已经处于Connected状态,但是其他命令如shell、install、file send等无响应或者报错,这时候一般是由于hdc的版本不一致造成的。

  • 我们在pc上使用的hdc_std.exe其实是HDC架构中的客户端,主要作用是与服务端进行沟通请求执行相应的hdc命令。

  • 服务端则是运行在pc的进程服务中,是由hdc_std.exe启动,其作用则是与运行在OpenHarmony设备中的守护进程沟通处理相应的请求。

由于HDC最近修改频繁,没有做前后兼容,因此版本不一致或者差距过大都可能造成命令执行失败或者无响应。可以按照如下步骤排查问题。

4.1 确保设备正常

请按照上文确保pc驱动安装正常,并且设备状态为Connected。

4.2 查看HDC版本
4.2.1 pc端
D:\sdk\toolchains>hdc_std -v
Ver: 1.1.1l
4.2.2 设备端
  • 检查设备能否响应hdc_std shell命令:

D:\sdk\toolchains>hdc_std shell hdcd -v
Ver: 1.1.1l
  • 如果shell命令无响应,可以连接设备串口,并在xshell等串口工具内使用hdcd命令查看。

  • 如果版本差距过大(如1.1.1l与1.0.1),则需要使用相近的版本:

    • 如果是pc侧版本过低,可以去DailyBuilds上下载较近的版本

    • 如果是设备内版本过低,则需要去DailyBuilds上下载较近的系统烧录到设备内,或者找更低版本的pc侧hdc。

4.3 关闭IDE

DevEco Studio会自己启动sdk内的hdc,可能会造成一定的影响,如果出现hdc连接问题,建议关闭DevEco Studio再排查。

4.4 查看进程

如果hdc版本一致,命令还是无响应则有可能是服务冲突:

如果电脑内有多个版本的hdc_std文件,并启动了hdc进程,那么不同版本之间会相互影响,我们需要在windows的任务管理器内杀死所有与hdc相关的进程后再使用我们需要的版本的hdc文件。

service

 

必要时可以重启电脑

4.5 中文路径

hdc对中文路径支持不友好,如果路径中带有中文,请将hdc文件拷贝到不带中文的目录中再执行。

4.6 查看日志

如果通过上述步骤后,还是有问题,可以查看日志文件再具体分析。

4.6.1 pc端日志

pc日志可以在文件管理器内输入%temp%并找到hdc.log文件。

4.6.2 设备端日志

设备端日志位于/data/local/tmp/hdc.log内。

5 常见的HDC命令

查看设备连接信息

hdc_std list targets

往设备中推送文件

hdc_std file send  E:\a.txt /data/local/tmp/a.txt

从设备中拉取文件

hdc_std file recv /data/local/tmp/a.txt D:\a.txt

安装应用

hdc_std install E:\***.hap

查看日志

hdc_std hilog

进入命令行交互模式

hdc_std shell

更多命令可以使用hdc_std -h查看,或访问https://gitee.com/openharmony/developtools_hdc_standard

查看日志

手机侧的开发可以直接在DevEco Studio内查看HiLog日志,但是OpenHarmony侧的暂时不行,我们需要使用hdc命令查看。使用如下命令:

hdc_std shell hilog

可以查看所有日志。

如果需要筛选,可以使用如下命令:

D:\sdk\toolchains>hdc_std shell
# hilog | grep 'error'
08-08 09:20:03.570   200   787 E 01800/SAMGR: CheckSystemAbility SendRequest error:3!
08-08 09:20:03.671   200   787 E 01800/SAMGR: CheckSystemAbility SendRequest error:3!
08-08 09:20:03.772   200   787 E 01800/SAMGR: CheckSystemAbility SendRequest error:3!

更多有关hilog的用法参考https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README_zh.md

参考文献

[1] OpenHarmony应用开发导读 . https://docs.openharmony.cn/pages/v3.1/zh-cn/application-dev/application-dev-guide.md/

[2] OpenHarmony开发者文档. https://gitee.com/openharmony/docs

Logo

社区规范:仅讨论OpenHarmony相关问题。

更多推荐