» » HƯỚNG DẪN TẠO VÀ CHIA SẺ THƯ VIỆN ARDUINO

HƯỚNG DẪN TẠO VÀ CHIA SẺ THƯ VIỆN ARDUINO

 

MỤC TIÊU – ĐỐI TƯỢNG – NỘI DUNG

Mục tiêu

Giúp các bạn nắm được căn bản cách thức tạo một thư viện Arduino có thể add vào Arduino IDE và chia sẻ với mọi người.

Đối tượng
Bài viết hướng tới mọi đối tượng muốn tìm hiểu thêm về Arduino, muốn tạo và chia sẻ các bộ thư viện của riêng mình.

Nội dung

  • Cấu trúc của một thư viện Arduino.
  • Cơ bản cách viết source thư viện
  • Thiết lập thư viện với library.properties và keywords.txt
  • Chia sẻ thư viện với File ZIP và Library Manager

Các công cụ hoặc kỹ năng như C++, Git, etc. sẽ được đề cập nhưng không được hướng dẫn.

CẤU TRÚC THƯ MỤC

Để bắt đầu tạo một thư viện Arduino có thể chia sẻ được, bạn nên tạo một thư mục có cấu trúc như sau:

myArduinoLib
|___src
|   |___myLib.cpp
|   |___myLib.h
|___examples
|   |___exp_1
|   |   |___exp_1.ino
|   |___exp_2
|       |___exp_2.ino
|___extras
|   |___api_doc.html
|   |___other_license.txt
|___library.properties
|___keywords.txt
|___README.md
|___license.txt

Đây là format chuẩn được hướng dẫn trong Arduino Style Guide, nó sẽ giúp Arduino IDE có thể nhận dạng và sử dụng thư viện của bạn. Chúng ta thử phân tích thư mục trên:

  1. Thư mục src, đương nhiên đây là nơi chứa source code. Nếu như thư viện cần tạo nhiều module con thì mỗi module con nên được tạo riêng một thư mục con trong thư mục src này. Và đương nhiên source code luôn đi theo một cặp *.cpp và *.h.
  2. Thư mục examples, chưa các sketch ví dụ cho thư viện của bạn. Chỉ cần nhớ rằng file *.ino cần nằm trong một thư mục cùng tên với nó.
  3. Thư mục extras sẽ được Arduino IDE bỏ qua khi bạn add thư viện, bạn có thể đặt ở đây các license liên quan, các tài liệu về API hoặc một easter egg be bé cho những kẻ tò mò tìm tới
  4. library.properties là file chứa các thiết lập của bộ thư viện
  5. keywords.txt chứa các keyword quan trọng của thư việc, giúp cho syntax hightlight của IDE làm nổi bật chúng lên.
  6. README.md đơn giản là một file README viết theo ngôn ngữ Markdown, dùng để miêu tả project của bạn. Rất có ích khi muốn miêu tả về thư viện hoặc hướng dẫn cách sử dụng.
  7. license.txt là giấy phép cho mã nguồn của bạn. Hiện nay đại đa số chúng ta chưa có khái niệm, thói quen về sử dụng giấy phép, nhưng nó khá là quan trọng đấy. Thường thì mình để MIT license (tức là source của tui muốn lấy làm gì đó thì làm).
Screenshot from 2017-11-02 15-07-53

Đây là cách file README.md hiển thị trên trang Github của bạn

CHUẨN BỊ SOURCE

Đương nhiên cốt lõi của thư viện là source code. Thư viện Arduino thường bao hàm một tính năng nào đó (như ArduinoJson sử lý chuỗi Json hay PubSubClient hỗ trợ giao thức MQTT) hoặc dùng để điều khiển một linh kiện nào đó. Vì thế thư viện Arduino được khuyến nghị nên “đóng gói” thành một class, nhở đó người dùng chỉ việc tạo các Object và sử dụng các Method có sẵn. Nếu như bạn đã đi tìm hiểu tới cách tạo và chia sẻ thư viện thì nghĩa là bạn đã có một trình code nhất định rồi, chỉ lưu ý vài khoản sau:

  • Nhớ #include trong cách header file.
  • Hãy viết như thể người dùng thư viện của bạn chả biết tí gì về lập trình cả
  • Các public function được cung cấp nên hỗ trợ đúng/vừa đủ những thứ người dùng cần (Ví dụ với cảm biến nhiệt độ chỉ cần đưa ra làm float readTemperature(), không cần đưa ra các hàm giao tiếp với cảm biến)
  • Tuy nhiên bộ thư viện vẫn nên có một cơ chế DEBUG nhất định, vừa giúp những người dùng nâng cao có khả năng truy cập sâu hơn vừa giúp sửa lỗi thư viện (đương nhiên tôi không tin bạn thần thánh tới mức quăng ra bộ thư viện không lỗi)
  • Sử dụng ngôn ngữ phổ thông dễ hiểu nhất có thể

Một trong nhưng lưu ý quan trọng là source của bạn chạy trên nền cấu trúc nào? Nếu như chạy được trên nhiều cấu trúc thì nên viết source theo dạng sau, chú ý nên có thông báo lỗi cho các cấu trúc không được hỗ trợ:

/* Ví dụ này copy từ web khác, tí trích nguồn sau */
#if defined(ARDUINO_ARCH_AVR)
  // AVR-specific code
#elif defined(ARDUINO_ARCH_SAM)
  // SAM-specific code
#else
  #error “This library only supports boards with an AVR or SAM processor.”
#endif

Sau khi soạn source xong test ngon lành thì hãy soạn thêm một vài sketch ví dụ đặt trong thư mục examples để hỗ trợ người dùng nhé. Lưu ý là trong các sketch này bạn phải include thư viện của mình vào #include (nói nghe thừa vãi).

THIẾT LẬP LIBRARY.PROPERTIES

Đây là file thiết lập cho thư viện của bạn, Arduino IDE sẽ tìm tới file này đầu tiên để kiểm tra thông tin về bộ thư viện. File này chứa các nội dung tối thiểu như sau:

name=easyFingerprint Library
version=1.4.0
author=HgN
maintainer=HgN 
sentence=Arduino library for interfacing to the Adafruit fingerprint sensor in much easier way.
paragraph=Arduino library for interfacing to the Adafruit fingerprint sensor in much easier way.
category=Sensors
url=https://github.com/HgN37/easyFingerprint
architectures=*

Trong đó:

  • name: tên của bộ thư viện
  • version: phiên bản
  • author: tác giả
  • maintainer: cần tên và email, trừ khi thư viện của bạn phổ biến tầm thế giới, không thì yên tâm chả ai mail bạn hỏi thăm gì đâu
  • sentence và paragraph: phần mô tả câu ngắn và đoạn mô tả dài, mở Library Manager lên sẽ thấy
  • url: dẫn tới trang source của bạn
  • architectures: cấu trúc (chạy trên AVR, ESP, etc.), nếu không quan tâm thì để dấu ‘*’

Ngoài ra còn một số thiết lập khác nâng cao nếu có hứng thú bạn có thể tìm hiểu sâu hơn trong mục THAM KHẢO.

Screenshot from 2017-11-02 15-57-01

Cách mà bộ thư viện sẽ hiển thị trong Library Manager sau khi add

SYNTAX HIGHLIGHT VỚI KEYWORDS.TXT

Đã bao giờ bạn thắc mắc tại sao chữ Serial hay SoftwareSerial có thể nổi màu cam, in đậm lên không? Đây là cách làm với file keywords.txt:

#######################################
# Syntax Coloring Map For easyFingerprint
#######################################

#######################################
# Datatypes (KEYWORD1)
#######################################

easyFingerprint	KEYWORD1

#######################################
# Methods and Functions (KEYWORD2)
#######################################

init 	KEYWORD2
save 	KEYWORD2
scan 	KEYWORD2
erase 	KEYWORD2
del     KEYWORD2
send    KEYWORD2

#######################################
# Constants (LITERAL1)
#######################################
FP_SUCCESS LITERAL1
FP_FAILURE LITERAL1

Đơn giản chỉ cần chọn từ muốn highlight và cách highlight thôi.

HOÀN THÀNH

Chỉ cần như vậy là bạn hoàn thành một thư viện của chính mình rồi. Cách test nhanh nhất là nến toàn bộ thư mục lại thành file zip, rồi vào Arduino IDE chọn Sketch -> Include Library -> Add .ZIP Library. Hãy hy vọng là bạn nhận được thông báo sau:

Screenshot from 2017-11-02 16-11-29

Thông báo thư viện thêm vào thành công

Khi đó bạn có thể vào Sketch -> Include Library sẽ thấy thư viện của mình và File -> Examples để tìm tới các ví dụ bạn đã thêm. Lúc này bạn có thể #include .
Cách thủ công nhất, nén file zip và gửi tới những ai cần. Mỗi khi có update gửi lại họ file zip mới…
Đùa thôi chả ai làm vậy đâu. Cách đơn giản nhất là push toàn bộ thư viện của bạn lên Github. Từ đó bạn có thể chia sẻ bằng hai cách sau:

  1. Bạn có thể share thư viện của mình trên Github, người dùng sẽ vào tải file ZIP về và cài đặt thông qua Sketch -> Include Library -> Add .ZIP Library. Sau này khi nâng cấp phiên bản bạn chỉ việc update trang Github của mình và những người dùng khác có thể dễ dàng update thư viện thông qua Library Manager.
  2. Library Manager có cơ chế quét các kho chứa source code miễn phí (như Github chẳng hạn), nếu nó phát hiện một kho chứa theo đúng tiêu chuẩn thư viện Arduino (cấu trúc cây thư mục, file library.properties, etc.) thì nó sẽ copy về server. Nếu như bạn tạo thư viện một cách chuẩn chỉ thì sau khi up lên Github tối đa 1 tiếng sau bạn có thể tìm được thư viện của mình thông qua Library Manager.

KẾT

Xài Arduino nhiều rồi, xài thư viện của người ta cũng nhiều rồi. Giờ cũng muốn tự viết thư viện cho mình, chia sẻ cho bạn bè dùng, chia sẻ cho mọi người dùng. Và giờ chia sẻ cách tạo thư viện cho mọi người, thế thôi.

Mời bạn xem thêm:

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)