Гайд для написання бібліотек в стилі Arduino

Документація

Як написати бібліотеку в стилі Arduino


Це гайд по написанню API бібліотек у стилі Arduino. Деякі з цих пунктів суперечать професійній практиці програмування. Ми усвідомлюємо це, але вони роблять можливим для багатьох початківців запросто розпочати роботу з Arduino. Тому, будь ласка, кодуйте, дотримуючись цих принципів. Якщо Ви маєте пропозиції, як зробити бібліотеки Arduino зрозумілішими для цієї ключової аудиторії, долучайтеся до дискусії. Це незавершена робота.

Будьте добрими до кінцевого користувача. Припустимо, Ви пишете API для розумної людини, яка не програмувала раніше. Придумайте чітку ментальну модель або концепцію, з якою Ви працюєте, та терміни і функції, які Ви використовуватимете.

Відповідність API до основних можливостей. Ви не хочете розкривати деталі виконання користувачу, але Ви також не хочете API, який пропонує неточну ментальну модель можливостей. Наприклад, якщо є лише кілька можливих варіантів для певного налаштування, не використовуйте функцію, яка захоплює int, це означає, що Ви можете використовувати будь-яке значення.

Організуйте свої публічні функції довкола даних і функцій, яких хоче користувач. Досить часто набір команд для специфічного електронного модуля є надзвичайно складним для більшості звичайних застосувань або може бути реорганізований навколо більш високого рівня функціональності. Подумайте про те, що пересічна людина думає про роботу бібліотеки та намагайтеся організувати функції API довкола цього. Бібліотека BMP085 від Adafruit є хорошим прикладом. Команда readPressure() виконує всі необхідні кроки, щоб отримати остаточний тиск. Бібліотека охоплює цей ряд часто виконуваних функцій у єдину команду високого рівня, яка повертає значення, потрібне користувачу, в очікуваному форматі. Вона абстрагується не лише від I2C-команд низького рівня, але й обчислень температури та тиску середнього рівня, все ще пропонуючи функції середнього рівня як публічні функції для тих, кому вони потрібні.

Використовуйте повні повсякденні слова. Не будьте небагатослівними, називаючи Ваші функції та змінні. Замість технічних термінів використовуйте повсякденні. Підбирайте терміни, які відповідають популярному сприйняттю підручної концепції. Не вживайте спеціалізованих знань. Наприклад, саме тому ми використовуємо analogWrite(), а не pwm(). Абревіатури прийнятні, якщо вони є в загальному використанні або основною назвою чогось. Наприклад, “HTML” є відносно поширеним, а “SPI” фактично назва цього протоколу (“послідовний периферійний інтерфейс”, мабуть, занадто довга). (“Wire” ймовірно був помилкою, оскільки протокол, який він використовує, зазвичай називається «TWI» або «I2C».)

Уникайте слів, які мають різні значення для загалу. Наприклад, для програмістів помилка є сповіщенням про те, що щось трапилося. Для широкої публіки помилки є поганими речами.

Коли Вам треба використати предметно-орієнтований термін, спочатку напишіть речення або два, який його описує, для широкої публіки. Ви, швидше за все, стикаєтеся з кращими термінами, а якщо ні, то розпочнете документацію Вашої бібліотеки.

Документуйте та коментуйте в процесі. Пишучи приклади та документацію, дотримуйтесь цього гайду стилю.

Використовувати встановлені основні бібліотеки та стилі.
  • Використовуйте read() для зчитування вхідних даних та write(), щоб записувати на виводи, наприклад, digitalRead(), analogWrite() тощо.
  • Використовуйте бібліотеки Stream.h та Print.h, маючи справу з потоками байтів. Якщо вони не підходять, щонайменше спробуйте їхній API як модель. Детальніше нижче.
  • Для мережевих додатків використовуйте як основу бібліотеки Client та Server.
  • Використовуйте begin(), щоб ініціалізовувати приклад бібліотеки, зазвичай з деякими налаштуваннями. Використовуйте end(), щоб припинити його.

В назвах функцій використовуйте різний регістр, а не підкреслення. Наприклад, analogRead, а не analog_read. Або myNewFunction, а не my_new_function. Ми перейняли це від Processing.org для читабельності.

ДОВГІ_ПОСТІЙНІ_НАЗВИ_ПОВНІ_КАПСУ важко читати. Намагайтеся спростити їх, де це можливо, але не будучи небагатослівними.

Намагайтеся уникати логічних констант. Натомість подумайте про надання двох різних функцій з іменами, які описують відмінності між ними.

Не враховуйте знання вказівників. Користувачі-початківці C вважають вказівники найбільшою перешкодою, їх дуже бентежать & та *, тому якщо Ви можете уникнути використання покажчиків в API, зробіть це. Один зі сособів уникнення — використання позначення масиву замість позначення *, наприклад

void printArray( char* array)

може бути замінене на

void printArray(char[] array)

Хоча існують деякі бібліотеки, де ми зустрічаємо покажчики, використовуючи структури, такі як const chars, уникайте всього, що вимагає від користувача зіткнення з ними. Наприклад, замість

foo.readAccel(&x, &y, &z)

використайте шось на кшталт:

xAxis = adxl.readX();

   yAxis = adxl.readY();

   zAxis = adxl.readZ();

Використовуючи послідовний зв'язок, дозволяйте користувачу вказувати будь-який об'єкт Stream, а не важке у кодуванні «Serial». Це зробить Вашу бібліотеку сумісною з усіма послідовними портами на Mega та Due, також можна буде використовувати альтернативні інтерфейси як-от SoftwareSerial. Об’єкт Stream може бути переданий конструктору Вашої бібліотеки або до функції begin() (як посилання, не як вказівник). Приклади кожного підходу на сторінках Firmata 2.3 та XBee 0.4.

Пишучи бібліотеку, яка забезпечує байто-потоковий зв’язок, наслідуйте клас Stream Arduino. Так Ваша бібліотека може бути використана з всіма іншими бібліотеками, які приймають об’єкти Stream. Якщо можливо, збережіть у буфері вхідні дані, таким чином read() негайно матиме доступ до даних у буфері, але не чекатиме більше на надходження даних. Якщо можливо, Ваш метод write() має зберігати дані у буфері передачі, але write() має чекати, якщо буфер не має достатньо місця для миттєвого зберігання всіх вихідних даних. Під час очікування слід викликати функцію yield().

Є кілька зразкових бібліотек від Adafruit. Вони дуже добре порушують функції пристрою в високому рівні їхньої діяльності. Серед них Adafruit BMP085 та DHT sensor. RTC добре абстрагується від бібліотеки Wire (I2C).

Повернутись до головної

Коментарі 0

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.