Skip to content

Latest commit

 

History

History
197 lines (150 loc) · 13.1 KB

README.md

File metadata and controls

197 lines (150 loc) · 13.1 KB
Raw

braille_display

Arduino PlaformIO Wokwi

This project implements a scalable multi-cell Braille display system using an Arduino - it converts input characters into their corresponding Braille patterns, providing accessibility for visually impaired users

project breadboard scheme

GitHub Actions Workflow Status - build.yaml GitHub Actions Workflow Status - check_readme.yaml

GitHub Latest Release GitHub License

Table of Contents

Preparation

1. In simulation via Wokwi

Note

If Wokwi-project link is broken or project there is corrupted, please report it to GitHub Issues, meanwhile:

  • Clone or download and unpack the repository
  • Start a blank Wokwi-project
  • Select diagram.json tab
  • Press ⏷ button to the right of 'Library Manager' tab, then - 'Delete' and confirm
  • Press ⏷ button once again, then - 'Upload file(s)...'
  • Select all files from the project's src/ folder and confirm
  • Press green 'Play' button to start the simulation

2. On real Arduino via PlatformIO in VSCode

  • Install Visual Studio Code and launch it
  • Install PlatformIO IDE extension for VSCode
  • Clone or download and unpack the repository
  • Open braille_display/ project's folder with VSCode
  • Connect your Arduino via USB to your computer

Note

Arduino Uno is set as default board in platformio.ini - if you use different board, do the following:

  • Click 'View'->'Command Palette...' (or press Ctrl+Shift+P)
  • Paste > PlatformIO: PlatformIO Home and press Enter
  • Select 'Projects' tab on the left
  • Search for the braille_display project and click 'Configure'
  • Choose your board in 'Platform Options'->'board'
  • Click 'Save' in the upper right corner
  • Press 'Upload' button in the upper right corner of VSCode window (or press Ctrl+Alt+U)

3. On real Arduino via ArduinoIDE

  • Clone or download and unpack the repository
  • Use an appropriate script from the project's scripts/ folder to change project structure (double click it or call it from console):
    • toggle.batch for Windows
    • toggle.bash for Linux

Note

The reason for this is that ArduinoIDE demands project <name>.ino main code file as well as all other code files to be located in the homonymous <name>/ folder

You can call this script repeatedly to toggle back and forth between ArduinoIDE and PlatformIO project structures

An alternative way is to do it manually:

  • Rename project's src/ folder to main/
  • Rename main.cpp file to main.ino
  • Open main.ino with ArduinoIDE
  • Connect your Arduino via USB to your computer

Warning

Make sure that:

  • all .h files are shown in the top tabs
  • board model selected in 'Tools'->'Board' matches your Arduino model
  • Press 'Upload' button in the upper left corner of ArduinoIDE window (or press Ctrl+U)

Usage

Send messages, that you want to translate and show, to the Serial Monitor

Press the button to display the next set of Braille patterns

Features

  • Program can translate following symbols into Braille:

    • Latin alphabet
    • Cyrillic alphabet
    • Digits
    • frequently used Punctuation

  • You can send messages one after another not waiting for the previous ones to be shown - program will try to concatenate them until the rx_buffer (receiving buffer) is full

  • You can hold the button instead of repeatidly pressing it - program will display the next number of characters on the defined time interval

  • You can easily scale the number of cells on the Braille display - the only change to the program you need to make is a single variable

  • Program will keep the last part of the last message displayed until you send a new message and then press the button

  • Program can process special cases of translating to Braille (e.g.: punctuation, modifiers, etc.)

    Examples:
    • capital modifier is required before capital letters: XyZ -> ⠠⠭⠽⠠⠵
    • numeric modifier is required before numbers: a 12 -> ⠁ ⠼⠁⠃
    • . (dot) symbol has different translations:
      • N.o -> ⠠⠝⠲⠕ (grammatical dot)
      • 8.9 -> ⠼⠓⠨⠊ (decimal dot)
    • * (asterisk) symbol is translated into a doubled ⠔ Braille pattern: 5 * 6 -> ⠼⠑ ⠔⠔ ⠼⠋
    • " (quote) symbol's Braille pattern alternates on opens and closes: m "q" n -> ⠍ ⠦⠟⠴ ⠝
    • " (quote) symbol, unpaired until EOM, is paired automatically: "k -> ⠦⠅⠴

  • Program doesn't process characters in advance - it translates the least neccessary amount of characters to fill the Braille display after you press the button

  • Program can wait for the next messages if last symbols of the current one don't have enough context to be translated to Braille correctly

    Examples:

    First comes 30. message

    • there is not enough context in the message for the . (dot) symbol to be translated to Braille
    • program sends ⠼⠉⠚ patterns to the display (without . symbol) and waits for the next message:
      • then comes 25 message -> program shows ⠨⠃⠑ (decimal dot)
        -or-
      • then comes re message -> program shows ⠲⠗⠑ (grammatical dot)

Configuration

You can configure the project to your liking:

Setting Category Type Default Notes
BUTTON_PIN PIN uint 7 -
AUTO_PIN PIN uint 8 pin that receives AUTOCOUNT signal
DATA_PIN PIN uint 11 74HC595 shift register - pin DS
LATCH_PIN PIN uint 12 74HC595 shift register - pin ST_CP
CLOCK_PIN PIN uint 13 74HC595 shift register - pin SH_CP
BAUD_RATE SRL uint 9600 Serial speed
SERIAL_ECHO SRL bool true if symbols must be printed to Serial as they are being sent to Braille display
LF_IS_EOM SRL bool true Linefeed is End-Of-Message
if false, messages before and after LF symbol are concatinated
SERIAL_NA_IS_EOM SRL bool false Serial Not Available is End-Of-Message
if false, messages before and after Serial-not-available event are concatinated
BUTTON_CLICK_MS BTN uint 100 min delay between consecutive clicks to prevent jitter (in ms)
BUTTON_CYCLE_MS BTN uint 1000 delay between autoclicks while button is kept pressed (in ms)
BRAILLE_CELLS CEL uint 4 number of Braille cells if they are not automatically counted
AUTOCOUNT_CELLS CEL bool true if Braille cells must be automatically counted
AUTOCOUNT_BIT CEL uint 7 bit number that contains AUTOCOUNT signal passed to AUTO_PIN
6th bit corresponds to Q6 shift register pin
7th bit - to Q7
ANIMATION_ON_START ANM bool true if to play animation on start
ANIMATION_MS_PER_CELL ANM uint 500 delay between each animation frame (in ms)

Configurations priority (from highest to lowest):

  1. platformio.ini
    • [ works only if you use PlatformIO ]
    • add required -D <setting>=<value> lines to build_flags section
    • if you want to change BAUD_RATE, consider editing monitor_speed instead
      (BAUD_RATE will be set automatically, ensuring Serial monitor speed is synchronized with it)
  2. src/custom_config.h
    • [ the preferred way ]
    • uncomment neccessary defines and set their values
    • keep in mind that settings from platformio.ini can override settings defined here
  3. src/config.h
    • [ please do not modify this file ]
    • contains default setting values

Todo

  • Add translations to README
  • Add tests
  • Add WokwiCI action

Contribution

Feel free to contribute to this project by submitting issues or pull requests!

License

This project is open-source and available under the MIT License