9月 262014
 

Last week, I was very honored to get sponsored to participate the Hanoi SFD 2014. I joined the Fedora meetup on Friday and gave a talk on Saturday. Below is the full report.

Day 0 (2014-09-18): Arrival Day

I left Beijing early in the morning and in the afternoon stayed in Hong Kong Airport to transfer. The flight to Hanoi was a bit late, and I arrived at the Hanoi Airport at around 8:00 PM (local time, 9:00 PM in Beijing time). The weather was wet and hot, but the people are nice. It took me some time to find a large shuttle bus, rather than the minibus. On the bus I met a Japanese guy, and it turned out he lived in a hotel not far from mine. So after getting off the bus, we walked to our hotels together most of the way.

It was about 10:00 PM when I arrived at the hotel. I shared a room with Sarup (banas), and he told me they (Thang, Somvannda, Tuan and others) would like to have me together go out for beer. I was a bit tired after the long trip, but after ten minutes’ rest, I joined them. Thang carried me on his motorbike to a street corner nearby, and I met Tuan (for the first time) and Somvannda (for the second time). I was surprised to find many people are there on the street at first. But I soon realized having cool beer outside is the best way to pass the hot night. By cool I mean not only temperature (ice beer), but also the taste (nice beer).

Day 1 (2014-09-19): Fedora Meetup

On Friday morning we went to the VAIP office and had a Fedora APAC ambassador meetup the whole day. The meetup was set up for APAC ambassadors to discuss critical tasks. EMEA has had a lot of similar meetups, but for APAC, it was the first to my knowledge. (It was at least the first in this year.) To include remote participants who cannot make it at Hanoi, we also joined the #fedora-apac IRC channel. There we met gnokii, kushal, FranciscoD, etc. We also set up a pad on PiratePad.

In the morning, we discussed many issues including the budget status, current issues and so on. It seems the major issue is that not many APAC ambassadors are active, and people do not regularly attend meetings. In China, the state is somewhat better: we do have a few active contributors and we managed to have regular IRC meetings and offline activities (release parties every release, yearly FAD, and FUDCon Beijing). In India there is another problem: there might be too many ambassadors and some people tend to use Fedora as a travel agency. We agreed that people need actively participate biweekly meetings and mailing list discussions to get their tickets approved easily, and to be considered as active, one ambassador needs to organize (or help organize) at least one event per year.

We also talked about the FAD Phnom Penh under planning and the ambassador Polo shirts. The FAD planning is generally in good shape. I saw no Taiwan ambassador registered the event but I think they should consider. Regarding the Polo shirts, unfortunately the Fedora logo on the sample shirt is incorrect and needs to be fixed. And the quality of the shirt is not quite high. I am supposed to ask local vendors in China to see if we can get better ones within a reasonable price. We went on to discuss general swag production issues. gnokii suggested that good quality can be produced in Europe for both EMEA and APAC regions. Besides, China can be one good candidate among the locations to store the swag.

I also learned from Tuan about why we APAC folks lose some money when getting reimbursed by paypal while Americans not. The reason is that US paypal accounts have the option to cover the transaction fee by the sender, while other accounts do not. So the fee is charged at the receiver side, causing the loss. To walk around the issue, we might let APAC CC holder izhar set up a US paypal account.

In the afternoon, after a short pizza lunch, we carried on remaining tasks. We spent quite some time in summarizing the budget usage in previous quarters. It was sad to find that none of the planned events in Q2 happened at last. To solve the budget problem, we adjusted the budget allocation for the remaining quarters, and came up with ideas of possible events. After that, we talked about Fedora sessions for the SFD next day. At last, Somvannda asked us to share stories of being an Fedora ambassador. For me, it was the simple idea of organizing regular events to gather existing contributors and attract newcomers, and the idea of starting something by oneself when no one else has started it.

IMG_4541

In the evening, we went to see the water puppet show, which is fun and amazing. At dinner we had delicious dishes and noodles, and Saigon beer! But we did not stay up too late at night, since we felt quite tired after one day’s meeting, and we need to prepare for SFD in the next day.

Day 2 (2014-09-20): Hanoi SFD 2014

Saturday was the Software Freedom Day (SFD), a global event to celebrate Free and Open Source Software (FOSS). I organized SFD in Tsinghua University last year, and it is lucky for me to be part of SFD Hanoi this year. Hanoi SFD is organized by VFOSSA, the FOSS association in Vietnam. Fedora was one main sponsor of the event. It was a whole day event held in a university. So many volunteers are students and employees of the university. It was fun that the event begins with volunteers dancing, both in the morning and in the afternoon, and they are so good at it!

In the morning are welcome and keynote sessions in one large lecture hall. Sarup, Somvannda, and I are honored to be introduced as special international guests to the event (in English). They awarded new members and event sponsors in the welcome session. Later in the keynote session, Tuan delivered a speech on seven ways to contribute to Fedora (without coding). Most of the morning sessions were in Vietnamese, and I could only understand a little bit. I brought some Fedora 20 DVDs, stickers, and flyers from China, and they were distributed very soon at the booth.

IMG_4624

In the afternoon, we had a dedicated room for Fedora related sessions. First, Thang gave a general introduction of the Fedora Project to the audience in Vietnamese. Then I talked about free and open source software defined radio (FOSS SDR). With a lot of examples, I introduced why we should have FOSS SDR, and how FOSS SDR can enable hacking in the radio frequency. I introduced GNU Radio and various SDR hardware such as HackRF and bladeRF to show how FOSS and open hardware play well with each other. Since the talk was in English, and the topic is not so familiar, the main purpose of the talk was to show the power of FOSS and open hardware, and to encourage the audience to try out and contribute to FOSS projects.

IMG_4710

Later on, Sarup delivered a FOSS 101 talk. He talked about why we should choose FOSS, how newcomers join and contribute to Fedora, and main communication tools of FOSS communities. Then he gave an introduction on Git and version control concepts. I helped demonstrate the git operations, and Trang helped translate for easy understanding.

At around 4:00 PM, we gathered to one room again. There was a panel Q&A session followed by the lucky draw. The panel session was quite interactive, and the audience raised many questions. One interesting thing is that the panel speakers voted for the best question and there was an award for that questioner. Then in the lucky draw, it turned out we foreigners were not so lucky. None of us was chosen. But lucky draw is always fun for everyone.

In the evening, we had dinner with the organizers and volunteers of SFD. We drank beer and toast to each other. I even learned how to toast in Vietnamese!

Day 3 (2014-09-21): One Day Tour

On Sunday, Somvannda and Sarup left for the airport early in the morning. My flight was around at 7:00 PM, so I took a one day tour in Hanoi. I visited Quang Truong Ba Dinh (Ba Dinh Square), Ho Chi Minh’s Stilt House, Ho Chi Minh Museum, One Pillar Pagoda, the Flag Tower, Hanoi Cathedral, and so on. The sight spots are relatively near to each other, so I travelled around mostly by walking. I had lunch at Quan An Ngon, a popular restaurant in Hanoi, and bought some candies and gifts to bring back to China. In the afternoon, on the way back to the airport, I also walked by the Ho Hoan Kiem (Hoan Kiem Lake). The sight spots are nice, and the food is delicious. So I enjoyed the trip to Hanoi a lot. Plus the warm support and help from Tuan, Thang, Somvannda, Sarup, and others, the days in Hanoi are quite memorable to me.

8月 272014
 

使用 bladeRF 板卡时我们会遇到两个“镜像”:固件 (firmware) 镜像与 FPGA 镜像。二者是两个不同的概念。但是业界叫法不一,有时候会把二者混为一谈。一般而言,固件指的是嵌入到硬件设备中的软件,存放在只读存储器 (ROM) 或者闪存 (flash) 中,一般不易修改,修改的操作称为“刷新”(flashing)。固件这个名词最初和微代码相关,不过 bladeRF 里源代码是嵌入式 C 程序。FPGA 全名为可编程门阵列,其门电路、寄存器连接可以编程重构,其源程序一般是硬件描述语言 (HDL),通过综合 (synthesis) 等步骤得到二进制文件。在 bladeRF 板卡上,FPGA 只是一块 Altera 芯片。在没有内置非挥发存储时,FPGA 镜像需要每次上电时重新加载,bladeRF 就是这种情况。所以在拿到板卡时,上面已有固件,但还没有 FPGA 镜像。下面本文会具体说明在使用 bladeRF 时如何刷新固件、加载/更新 FPGA 镜像、以及如何自动加载 FPGA 镜像。注意,有时为了避免混淆,会称 FPGA 镜像为 FPGA 比特流 (bitstream),或者 FPGA 配置(因为它就是配置了门电路等组件的连接)。

刷新固件

注意:刷新固件前请先取消 FPGA 自动加载,以避免可能的冲突。FPGA 自动加载的细节参见下文。

Nuand 官方提供固件的源码,我们可以自行编译,不过这需要一套嵌入式开发工具链。Nuand 也提供构建好的固件镜像,可以直接下载使用。要刷新固件,只需在命令行执行:

bladeRF-cli -f bladeRF_fw_vX.Y.Z.img -v verbose

其中 X.Y.Z 为具体的版本号。命令完成后,需要断电重启了 bladeRF。然后可以用 bladeRF-cli 工具检查:

$ bladeRF-cli -e version

  bladeRF-cli version:        0.11.1-git-c631100
  libbladeRF version:         0.16.2-git-c631100

  Firmware version:           1.7.1-git-ca697ee
  FPGA version:               Unknown (FPGA not loaded)

看下其中 Firmware version(固件版本)是否更新。

事实上,还有另外一种刷新固件的方法,是通过进入设备的启动加载 (Bootloader) 模式(类似 Android 的 Recovery),输入一些命令完成的。不过这种方式步骤繁琐,一般不推荐使用,建议在上述简单方法遇到错误时考虑采用。具体步骤参加维基

加载 FPGA 镜像

注意到上面的示例中,FPGA version(FPGA 版本)显示为 Unknown(未知),FPGA 未加载。目前 bladeRF 使用两种 FPGA。要加载正确的 FPGA 镜像,首先需要确定手头 bladeRF 板卡的 FPGA 尺寸。它可以根据当初购买的价格判断,但更靠谱的方法是使用命令行查看:

$ bladeRF-cli -i
bladeRF> info

  Serial #:                 4f977f01eec48f5068c2ee3aeba41ba9
  VCTCXO DAC calibration:   0x8b63
  FPGA size:                40 KLE
  FPGA loaded:              yes
  USB bus:                  4
  USB address:              5
  USB speed:                SuperSpeed
  Backend:                  libusb
  Instance:                 0

交互模式下用 info 命令,或者直接在命令行下 bladeRF-cli -e info,在输出中寻找 FPGA size,就可以看到 FPGA 尺寸信息。这里示例显示板卡使用 40 KLE FPGA。事实上,FPGA 尺寸还可以通过查看 FPGA 芯片上的 EP4CExxxF23C8N 字样中 xxx 的部分来获得。

Nuand 官方提供了预先构建的 FPGA 镜像,免除用户手工编译之苦。40 KLE FPGA 对应 hostedx40.rbf 文件,以此类推。要加载 FPGA 镜像,只需使用命令 bladeRF-cli -l /path/to/fpga/file,或者交互模式下 load fpga /path/to/fpga/file,其中 /path/to/fpga/file 为 FPGA 镜像所在路径。FPGA 镜像成功加载后,板卡上的三个 LED 灯会亮起,交互模式下 version 命令可以看到 FPGA 版本不再是未知。

不过,正如前文所说,每次重新加电后,FPGA 镜像都需要重新加载。下面说下如何自动加载 FPGA 镜像。

自动加载 FPGA 镜像

bladeRF 维基上提供了两种自动加载 FPGA 镜像的方法。第一种方法基于主机软件,libbladeRF 在打开设备时,会在如下目录自动搜索合适的 FPGA 镜像:

  • $HOME/.config/Nuand/bladeRF/
  • $HOME/.Nuand/bladeRF/
  • /etc/Nuand/bladeRF/
  • /usr/share/Nuand/bladeRF/

只需将下载的 FPGA 镜像文件放在上述目录之一(没有可以新建之),即可实现 FPGA 镜像的自动加载。

另一种方式是将 FPGA 镜像写入设备的 SPI 闪存。这种方式的好处是写入后就不再依赖主机,从而可以实现脱机运行。不过这种方式比较慢,加载 x40 镜像需要大约 4 秒钟。注意绝对不要在加载完成,三个 LED 灯亮起前试图使用设备。要使用这种方式,需要执行下面命令:

bladeRF-cli -L /path/to/fpga/file

一般说来,如果没有脱机工作的需求,还是推荐第一种自动加载方法。

前面提到,刷新固件时最好取消自动加载。对于第一种方法,只需把 FPGA 镜像文件临时移走。第二种方法,则需要执行命令 bladeRF-cli -L X,以擦除写入的 FPGA 镜像。

致谢

本工作由星天科技赞助。

8月 102014
 

bladeRF 维基上介绍了在 Linux 系统上搭建 bladeRF 环境的步骤,不过原文是英文的,另外其中一些具体选择不尽合理。本文以 Fedora 系统为示例,提供一个中文版的 bladeRF 环境搭建指南,并着重介绍和维基上的不同点。比较可能有一定的时效性,但一些原则应该足够通用。本文的比较基准是当前的维基版本

安装依赖

维基上建议安装 “Development Tools” “Development Libraries” 两个软件包组,但我们只需要其中的一部分软件包,其中有些可能已经安装过了,而像 cvs 等并不必须。如果你像我一样有“洁癖”,不希望安装不需要的软件包,那么可以用如下的命令安装必须的依赖(未严格验证,在我这里绝大多数包都在之前安装过了):

sudo yum install git doxygen gettext glibc-devel ncurses-devel readline-devel zlib-devel boost-devel
sudo yum install libusbx libusbx-devel cmake wget gcc-c++

注意其中是 libusbx 而非 libusb,后者是 0.x 系列的版本,而非 1.x 系列。Debian/Ubuntu 系的用户会注意到软件包命名上的差异 (devel 而非 dev)。

维基上推荐安装 libtecla,以增强 bladeRF-cli 交互模式的编辑功能。不过 Fedora 软件源里目前还没有这个包,所以需要手动下载,解压缩,使用经典的 ./configure; make; sudo make install 三部曲安装。

构建 bladeRF

在终端下进入打算用来放置 bladeRF 源码的目录,用 git 将 bladeRF 的源码库克隆下来:

cd /path/to/bladeRF/directory
git clone https://github.com/Nuand/bladeRF.git

切换到源码目录中的 host 目录,创建一个 build 目录用来存放构建过程的中间文件。这种使用单独的构建目录的方式称为树外构建 (out of tree build),相对于直接在源码目录构建,好处在于生成的中间文件不会分散在源码目录里,方便清理,另外可以用多个构建目录构建出互不干扰的不同参数下的版本。之后切换到构建目录,然后就是标准的 cmake ..; make; sudo make install 三部曲了。注意这里 cmake 时启用了 INSTALL_UDEV_RULES 宏,使得安装时把 udev 规则文件也安装到系统中。

cd bladeRF/host/
mkdir build
cd build
cmake -DINSTALL_UDEV_RULES=ON ../
make
sudo make install

很遗憾的是这里安装的 udev 规则文件使用了 plugdev 群组,不是 Fedora 下的标准做法。可以参考之前的博文修改 udev 规则文件。

为了让新安装的 bladeRF 库文件可以被二进制文件使用,我们需要用 ldconfig 刷新系统动态库的缓存。上面的构建过程会将 bladeRF 安装到 /usr/local 下,而其中的库文件目录 /usr/local/lib{,64} 不在 ldconfig 的默认搜索路径里。所以我们可以将它们添加到 /etc/ld.so.conf 里。添加之后文件内容如下:

/usr/local/lib
/usr/local/lib64
include ld.so.conf.d/*.conf

之后,用 sudo ldconfig 刷新缓存即可。可以用 ldd /usr/local/bin/bladeRF-cli 命令检查 bladeRF 库文件是否被找到。连上 bladeRF 设备,用 bladeRF-cli -p 命令看下是否能够发现设备。更多操作见于另一个维基页

构建 GNU Radio 与 gr-osmosdr

通过上述步骤,就可以操作 bladeRF 板卡了。但是,要想便捷地为 bladeRF 开发软件无线电应用,最好再构建一下 GNU Radio 和 gr-osmosdr。GNU Radio 是一个开源的软件无线电开发平台,提供众多的信号处理模块和简单易用的图形界面开发环境。gr-osmosdr 适配 GNU Radio,为众多硬件板卡(除了 bladeRF 之外还有 HackRF 等)提供一个统一的软件接口。

GNU Radio 依赖比较多,编译安装相对麻烦,一般推荐使用 build-gnuradio 脚本。但是因为其中涉及到从网络下载诸多软件以及编译安装,效率受网速和电脑硬件性能限制,耗时较长。另外,脚本的健壮性不高,所以很容易中途退出。这个脚本很长,但实际上是把整个构建过程划分为几个步骤,放在几个函数里先后执行的。我建议阅读这个 Shell 脚本,每次运行其中的一步或几步,必要时手动完成一些配置。对于新手,这会是一个很好的通过阅读代码学习 Shell 编程的机会。

具体的构建步骤可以在维基或这里找到,这里就不再赘述。只是提几点注意事项:

  • 如果你像我一样,除了 bladeRF 之外,还会使用 Ettus 公司的 USRP 系列设备,那么记得先构建 UHD,然后构建 GNU Radio。
  • build-gnuradio 脚本在 cmake 时,有时用了树外构建,但有时又没用。建议始终用树外构建。
  • 编译 GNU Radio 时,并行 make (make -j N 其中 N 大于 1)时有时会编译失败(竞态条件?),直接 make 就可以正常编译通过,虽然速度会慢很多。什么?make 也会出错?那考虑换一个 git 提交重新编译,并向上游报 BUG 吧。

构建成功 GNU Radio 后,构建 gr-osmosdr 就显得小菜一碟了,标准的 cmake 构建三部曲,项目不大,编译过程也能很快完成。

全部构建完成后,可以使用如下命令用 bladeRF 看一下频谱,检验是否大功告成。其中 FPGA 映像可以从 Nuand 网站下载。此外,最新固件也可以从官网下载。

osmocom_fft -a bladerf=0,fpga=<your FPGA image> -s 2000000 -f 446000000

致谢

本工作由星天科技赞助。

8月 072014
 

最近,我发现 Fedora 系统上没有 plugdev 群组,而是使用动态 ACL 的方式允许普通用户访问可插拔设备等。

事情的缘由是我在折腾软件无线电 (SDR),更特别的说就是 bladeRF,它在编译安装时会自动安装相应的 udev 规则,以使得普通用户可以访问这块板卡。它提供的 udev 规则文件为 /etc/udev/rules.d/88-nuand.rules,内容如下:

# nuand bladeRF
ATTR{idVendor}=="1d50", ATTR{idProduct}=="6066", MODE="660", GROUP="plugdev"

# Reserved for future bladeRF-specific bootloader
ATTR{idVendor}=="1d50", ATTR{idProduct}=="6081", MODE="660", GROUP="plugdev"

# Cypress Bootloader
ATTR{idVendor}=="04b4", ATTR{idProduct}=="00f3", MODE="660", GROUP="plugdev"

其含义是将 bladeRF (以及相关设备)的权限设为仅属主和群组可读写,群组设为 plugdev。类似的使用 plugdev 群组的 udev 规则设置,在许多涉及可插拔外设的上游项目里都会看到。

然而事实上 Fedora 系统上是没有 plugdev 群组的。bladeRF 维基建议手动建立该群组,并将当前用户添加进去。 但这种做法其实是不被 Fedora 推荐的,原因是这种静态的设备管理群组

  • 不安全。考虑这样的一个场景:一个 SSH 远程登录的用户可以访问物理主机的摄像头、麦克风,只要他是该群组的成员。
  • 不灵活。需要手动地维护该群组的成员列表,新增用户还需要注销当前会话重启会话才能使用该设备。
  • 不具体。plugdev 群组的用户可以使用任何可插拔设备,不论这个设备是手机、摄像头还是麦克风。

Fedora 支持动态的权限控制 (ACL),可以根据用户会话状态、物理座位(seat)配置来决定是否授权设备。在这种机制下,udev 规则文件可以是简单的一行

SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", \
  ATTRS{idVendor}=="1ed8", ATTRS{idProduct}=="000[456]" \
  ENV{ID_<some_name>}="1"

这里的 ID_<some_name> 是设备的一个“合适”的类别,例如 ID_CDROM, ID_MEDIA_PLAYER 等。它会出现在 Systemd 的 uaccess 规则文件 70-uaccess.rules 中,这个文件会授权此类设备给活跃用户。

遗憾的是,目前 uaccess 规则文件里并没有一个软件无线电有关的设备类别。所以暂时只能像如下的 udev 规则文件中那样,直接给设备加上 uaccess 的标签:

SUBSYSTEM!="usb", GOTO="nuand_rules_end"
ACTION!="add", GOTO="nuand_rules_end"

ATTR{idVendor}=="1d50", ATTR{idProduct}=="6066", TAG+="uaccess"

# Reserved for future bladeRF-specific bootloader
ATTR{idVendor}=="1d50", ATTR{idProduct}=="6081", TAG+="uaccess"

# Cypress Bootloader
ATTR{idVendor}=="04b4", ATTR{idProduct}=="00f3", TAG+="uaccess"

LABEL="nuand_rules_end"

注意 udev 规则文件命名时开头的数字编号需要小于 70,此时 uaccess 才会生效。如果设备已经连接到电脑上,要使新添加的或新修改的规则生效,还需要 udevadm trigger 一下。

事实上,邮件列表并不推荐上述做法,udev 与 Systemd 开发者 Kay Sievers 表示设备规则文件不应该直接设置 uaccess 这一标签。我已经在 systemd-devel 邮件列表上请求添加一个软件无线电相关的设备类别,得到了肯定的回应,并最终在这次提交中添加了 ID_SOFTWARE_RADIO。在不远的将来,带有这一改动的 Systemd 进入主流发行版后,我们将可以通过在 udev 规则文件中使用类似 ENV{ID_SOFTWARE_RADIO}="bladerf" 的语句,让普通用户以一种更安全灵活的方式使用软件无线电外设。