OpenHisiIpCam/br-hisicam

BR-HisiCam

Buildroot based sample firmware for HiSilicon`s System-On-a-Chip ip cameras

Part of OpenHisiIpCam project

📝 Table of Contents

• About
• Getting Started
• Deploy
• Technical notes
• Target hardware

👓 About

This repo is freezed, will not be maintained or improved.

This repo can be used as starting point for ip camera research or some other associated project.

Here term firmware means full set of software needed for running embedded device. In our case it is bootloader, Linux kernel, filesystem, that contains full software set including system utilities, applications that manage audio/video pipeline, business logic and service functions.

Currently this repo covers just few tasks, it is mostly empty system that runs one application (that itself lacks all needed functionality), but we are working on improvement of different aspects of overall functionality.

🏁 Getting started

This is quick tutorial how to prepare source tree and build kernel and root file system image.

All these were developed and tested under Ubuntu 18.04/19.10 GNU/Linux OS. Supposed that everything will work on any modern GNU/Linux distro, deb based distros most probably have same system dependency packages names, on other distros satisfy deps by yourself.

1. Clone repo:

foo@bar:~$ git clone --recursive https://github.com/OpenHisiIpCam/br-hisicam --depth 1

2. Install required system packages:

foo@bar:~$ sudo make install-ubuntu-deps

Let us know if we miss some dependencies!

3. Prepare source tree:

foo@bar:~$ make prepare

During this step buidlroot source archive (~7MB) will be downloaded and unpacked.

4. List avalible boards/modules:

foo@bar:~$ make list-configs 
jvt_s274h19v-l29_hi3519v101_imx274
unknown_unknown_hi3519v101_unknown

5. Build toolchain, kernel and rootfs for choosen module:

foo@bar:~$ make BOARD=jvt_s274h19v-l29_hi3519v101_imx274 all

During build step, toolchain will be generated from scratch, that takes time and requires all deps sources to be downloaded. Downloaded data is about 200MB.

All artifacts reside in output directory that is ./output by default. However you may override it with OUT_DIR=path/to/my/output make variable. This output directory will be referenced below as OUT_DIR.

🕧 Overall build process (dependencies download time not included) can take:

• about 15 minutes on Intel(R) Core(TM) i7-4770 CPU @ 3.40GHz, 16GB RAM
• about 20 minutes on Intel(R) Core(TM) i7-2600K CPU @ 3.40GHz, 16GB RAM
• about 50 minutes on Intel(R) Core(TM) i7-5500U CPU @ 2.40GHz, 8GB RAM
• about 22 minuts on Intel(R) Core(TM) i5-8250U CPU @ 1.6GHz, 8GB RAM

Directory OUT_DIR/images contains kernel and rootfs images:

foo@br:~/br-firmware/output/images$ tree .
.
├── rootfs.squashfs	# XZ compressed SquashFS root file system
└── uImage		# U-Boot wrapped XZ compressed kernel image

0 directories, 2 files

Now you can deploy software to your camera module!

🔥 Deploy

This short deploy guide assume that you are familiar with your hardware, you made all wire (power, network and debug UART) connections and so on.

Prepare host machine

For developing purpose we recommend upload kernel and rootfs (as initramfs) into the RAM of the device, not writing it to ROM. In this case your expiriments will not affect normal device operation, after reset/poweroff of the device it will be at same state as before, becasue ROM data will still contains factory firmware.

Such way requires access to device`s bootloader (U-Boot in our case) and supposed that it will have tftp, bootm commands and avalibity of network operation.

As U-Boot will download kernel and rootfs images via TFTP, you have to install and tune tftp server on your host machine. In our case it will be tftpd-hpa, but you can use any you are familiar with.

foo@bar:~$ sudo apt-get install tftpd-hpa
foo@bar:~$ cat /etc/default/tftpd-hpa 
# /etc/default/tftpd-hpa

TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/home/foo/br-firmware/tftp" # <--- change path to your actual dir
TFTP_ADDRESS=":69"
TFTP_OPTIONS="--secure"

After changes don`t forget to restart tftpd-hpa

foo@bar:~$ sudo /etc/init.d/tftpd-hpa restart

Your test facility will be look like following schema.

Network configuration is sample, you can use any consistent network settings for your host machine and camera module.

Upload software via U-Boot

Your USB-TTL adapter will be registered in system as /dev/ttyUSB0 or in some cases as /dev/ttyACM0. You can use any serial terminal app like putty, miniterm or even screen 99% of known camera modules have U-Boot setuped for 115200,8n1 serial communication.

After camera power on quickly press Ctrl+C (send Ctrl+C to camera trough serial connection) to interrupt normal boot process. When you will catch U-Boot prompt hisilicon # (sometimes xm #, Zview #, etc) you ready to input commands.

1. Setup network settings and ip of tftp server (your host machine ip)

hisilicon # setenv ipaddr 192.168.1.100; setenv netmask 255.255.255.0;  setenv serverip 192.168.1.1;

Next steps will require chip and board specific information! TODO make jvt_s274h19v-l29_hi3519v101_imx274_info

2. Download kernel and rootfs images from your host machine tftp server

hisilicon # tftp 0x82000000 uImage
hisilicon # tftp 0x82400000 rootfs.squashfs

3. Setup kernel boot params.

hisilicon # setenv bootargs mem=64M console=ttyAMA0,115200 root=/dev/ram initrd=0x82400000,4M

4. Finally let U-Boot load Linux kernel

hisilicon # bootm 0x82000000

Deploy to ROM is another story and at the moment it is out of scope this document.

📓 Technical notes

All system is built on top of the Buildroot (br for short). HiSilicon SoCs support made as buildroot external tree (br-ext-hisicam dir). For some reason we need flexible way of vanilla kernel patching (we wanted to support orderable patches and files overlay apply), so we made such extension.

External tree structure

.	#br-ext-hisicam dir contains following data
├── Config.in
├── board
│   ├── hi3516av100				# hi3516av100 family dir
│   │   ├── hi3516av100.config			# key=value chip specific settings
│   │   ├── hi3516dv100.config			# ---//---
│   │   └── kernel				# patches and files overlay for vanilla kernel
│   │       ├── hi3516av100.generic.config	# kernel default config
│   │       ├── hi3516dv100.generic.config	# kernel default config
│   │       ├── overlay				# kernel files overlay dir
│   │       └── patches				# kernel patches dir
│   ├── hi3516av200				# o
│   ├── hi3516cv100				#  t
│   ├── hi3516cv200				#   h
│   ├── hi3516cv300				#    e
│   ├── hi3516cv500				#     r
│   ├── hi3516ev200				# families, orginized similar way
│   ├── jvt					# JVT modules dir
│   │   └── jvt_s274h19v-l29_hi3519v101_imx274	#
│   │       ├── config				# key=value board specific settings
│   │       └── kernel				# Kernel specific data, like configs, patches overlay
│   ├── ruision					# another module vendor dir
│   ├── ssqvision				# ---//---
│   ├── xm					# ---//---
│   └── generic                                 # generic boards dir
│       ├── unknown_unknown_hi3516av100_unknown # similar to vendor modules dir (jvt, xm, etc)
│       ├── unknown_unknown_hi3516av200_unknown # can be used for initial RnD with new modules
│       ├── ...
│       └── unknown_unknown_hi3519v101_unknown
├── configs					# all generic and board specific buildroot configs 
│   ├── jvt_s274h19v-l29_hi3519v101_imx274_defconfig
│   ├── unknown_unknown_hi3516av100_unknown_defconfig
│   ├── ...
│   └── unknown_unknown_hi3519v101_unknown_defconfig
├── external.desc
├── external.mk
├── linux				# kernel standard br package extension
│   ├── Config.ext.in			# inserts hisi_patcher after vanilla source tree unpack
│   └── linux-ext-hisi_patcher.mk	# see 17.20.2 linux-kernel-extensions (br manual)
└── package
    ├── gohisicam			# GoHisiCam package TODO 
    └── hisi_patcher			# package apply patches and file overlays in orderable way

Long story short, when it comes to kernel, after vanilla sources unpack, br will apply chip family patches, overlay chip family files, than so same for board specific data. Exact actions are setuped in BR2_LINUX_KERNEL_EXT_HISI_PATCHER_LIST br config param (cat ./br-ext-hisicam/configs/jvt_s274h19v-l29_hi3519v101_imx274_defconfig | grep BR2_LINUX_KERNEL_EXT_HISI_PATCHER_LIST).

We recommend you take a look on Buildroot documentation, in case you want detailed understanding externel tree ideology.

📷 Target hardware

This project mostly targetted on HiSilicon based one cmos ip camera modules.

More information about different ip camera modules in the catalog.

We name modules according following schema {vendor}_{model}_{chip}_{cmos}.

Examples:

• jvt_s226h19v-l29_hi3519v101_imx226
• xm_ipg-83he20py-s_hi3516ev100_imx323
• jvt_s274h19v-l29_hi3519v101_imx274
• xm_ivg-hp201y-se_hi3516cv300_imx323
• ssqvision_on290h16d_hi3516dv100_imx290

Also there are generic profiles:

• unknown_unknown_hi3516dv100_unknown
• unknown_unknown_{chip}_unknown

Generic profile supposed to run on the module based on corresponding chip, but only debug UART will works, other periphery like network, should be tuned. Such profiles can be used as starting point for new modules research.

Hardware structuring

HiSilicon has a lot of chips, not only special ip camera solutions, but also NVR/DVR and even smartphone SoCs. Unfortunately it is hard to understand their naming policy, it is not random, but there is no strict patterns.

We split chips into groups, that we call families. Not sure that it is official HiSilicon`s term, but anyway such grouping reduce naming mess a bit.

Family - chips that have similar CPU architecture, similar audio/video pipeline hardware and shares same SDK. Software across family is binary compatible. Family name is repeating some chip name from corresponding group, usually (but not always) that chip is most powerfull chip across the family.

Chip families information

Tests

At the moment test covers:

• load kernel and rootfs to RAM via uboot/tftp (hiburn test)
• successful linux start with simple network echo server (minimal kernel config test)
• GoHisiProbe TODO (kernel and sdk modules consitency, minimal board params test)