b.note v2.0.0 Manuel du développeur (2022-09-11) ________________ SOMMAIRE Description 4 Matériel nécessaire 4 Accès aux sources de b.note 4 Connexion à b.note 5 Avec filezilla si l’adresse ip de b.note est 192.168.1.10 5 En ssh 5 Activation de l’option de développement 6 Développement sur b.note sans PycharmPE 6 Développement Sur PC avec PyCharmPE (Professional Edition) 7 Installation 7 Activation de la licence d’essai 7 Configuration du ‘Python Interpreter’ 7 Structure de l’application 11 L’application 11 Les événements clavier 11 Clavier de commande 11 Clavier braille 11 Clavier curseur routine 12 Autres évènements 12 Fonction 12 Timer 13 Le rafraîchissement de la plage braille 13 Objets standards 13 Les menus 13 Les boîtes de dialogue 14 Eléments 14 Boîtes de dialogue prédéfinies 15 Gestion du braille 15 Les fonctions clés 15 Synthèse vocale 15 ________________ Description Ce manuel décrit comment développer une nouvelle application dans b.note. Les applications internes de b.note sont entièrement écrites en python 3 sur une RaspberryPi 3 modèle A+. L’interface utilisateur de ces applications a été écrite de façon à permettre un développement rapide de nouvelles applications. Elle donne accès à : * Une barre de menu, * Des boîtes de dialogue, * Une zone document ayant accès aux événements clavier et à l’affichage en braille, * Une synthèse vocale. Matériel nécessaire * Un ordinateur personnel pouvant supporter “Pycharm Professional Edition”, * Un b.note, * Une connexion wifi. Note : L’utilisation de PycharmPE permet la pose de points d’arrêt, la visualisation des variables et le pas à pas sur un programme s’exécutant sur b.note (remote debugging). C’est de loin la méthode de développement la plus confortable. Il est néanmoins possible de modifier le source de l’application directement sur b.note sans outils de développement. Accès aux sources de b.note Les sources de b.note sont la propriété d’Eurobraille, un développeur ou une société voulant développer une nouvelle application devra donc en faire la demande à Eurobraille qui lui enverra l’intégralité des sources. C’est avec plaisir que nous vous remercions de l’intérêt que vous portez à notre produit et si vous réalisez une application qui peut profiter à l’ensemble des utilisateurs de b.note nous sommes prêts à l’intégrer dans la version officiel de b.note. Connexion à b.note Dans les préférences de b.note, il est possible de définir une connexion wifi, il faudra pour cela connaître le ssid et le mot de passe wifi de l'endroit où l’on se trouve et se rapporter au manuel utilisateur de b.note. b.note est paramétré pour demander une adresse ip au serveur dhcp du réseau local. Cette adresse est visible dans les préférences de b.note (rubrique wifi). Une fois ces étapes accomplies, b.note est accessible en console ssh ou avec filezilla par exemple. login : pi mot de passe : euroberry Avec filezilla si l’adresse ip de b.note est 192.168.1.10 En ssh $ssh pi@192.168.1.10 pi@192.168.1.10's password: Linux raspberrypi 5.10.63-v7+ #1488 SMP Thu Nov 18 16:14:44 GMT 2021 armv7l The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. Last login: Wed Jan 12 09:54:12 2022 from 192.168.1.60 pi@raspberrypi:~ $ Activation de l’option de développement Une option de développement permet de passer b.note en mode développement. Pour cela modifier le fichier /home/pi/.b.note/settings.txt en remplaçant la ligne : "system": { "braille_type": "dot-8", "games": false, "developer": false }, en : "system": { "braille_type": "dot-8", "games": false, "developer": true }, Une fois ce paramètre modifié et après redémarrage de b.note : * Une application exemple ‘skeleton’ se trouve dans la barre du menu application. Cette application permet de voir comment une application peut gérer ses menus, ses boîtes de dialogue, l’afficheur braille et les événements clavier. Les premiers essais pourront être réalisés en modifiant cette application. Développement sur b.note sans PycharmPE Il est possible de modifier les fichiers souces (.py) de b.note soit localement en ssh avec nano par exemple ou en copiant le dossier de source sur un système, puis de réaliser les modifications sur ce système et enfin en copiant le dossier modifié sur b.note. Vous devrez ensuite relancer l’application: Solution 1 : En rebootant la pi, si vous êtes connecté en ssh, faire : pi@raspberrypi:~ $reboot Solution 2 : En arrêtant le service b.note et en lançant manuellement l’application : Arrêter le service de lancement de l’application : pi@raspberrypi:~ $sudo systemctl stop bnote.service Lancer manuellement l’application : pi@raspberrypi:~ $cd b.note pi@raspberrypi:~/b.note $python b.note_start.py Cette seconde méthode à l’avantage de rendre en ssh les traces de l’application visibles sur la console. Développement Sur PC avec PyCharmPE (Professional Edition) PyCharmPE contrairement à la version CE (Community Edition) permet le “remote debugging”. Nous l’avons testé sous Ubuntu et Windows et elle existe aussi pour Mac. Cette version de PyCharm est sous licence (Il existe une version d’essai limitée à 30 jours), l’éditeur JetBrain propose différents abonnements dont un mensuel. Installation * Télécharger une version sur https://www.jetbrains.com/pycharm/ * Sous linux : Extraire le fichier tar.gz et suivre les instructions du fichier * Sous Windows : Lancer l’installateur (.exe) Activation de la licence d’essai Cliquez sur Log in to JetBrains Account… Configuration du ‘Python Interpreter’ Cliquez sur le bouton avec engrenage, puis sur Add Pour plus d’information consulter le lien suivant : https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html ________________ Structure de l’application Le code source se trouve le dossier /home/pi/b.note Le dossier documents visibles depuis l’application se trouve dans /home/pi/.b.note L’application Toutes les applications de b.note dérivent d’une classe b.noteApp située dans le fichier b.note_app.py. C’est grâce à cette classe de base que fonctionne les menus, les boîtes de dialogue et le mécanisme de rafraîchissement braille de l’application. Les événements clavier Les évènements clavier ont été catégorisés en 4 types qui correspondent chacun à une fonction python de l’application, elle viennent surcharger celles de la classe de base, il est donc important qu’elles appellent les fonctions de la classe de base tel que cela est fait dans skeleton.py pour assurer le bon fonctionnement des boîtes de dialogue et des menus. Clavier de commande L’appui sur une ou plusieurs touches des 2 pavés de 4 touches déclenchent l'événement ci-dessous : def input_command(self, data, modifier, key_id) -> bool: """ Does what is expected for this command key. :param data: ? :param modifier: bits field (see Keyboard.BrailleModifier) :param key_id: (see Keyboard.KeyId) :return: True if command treated, otherwise False """ Note : Un évènement avec un key_id = Keyboard.KeyId.KEY_NONE est généré lorsque toutes les touches sont relâchées. Il est à ignorer pour les applications de b.note. Clavier braille Le combinaisons de touche du clavier braille sont réparties en 2 catégories : * Les combinaisons conduisant à un caractère alphanumérique (input_character()) * Les combinaisons conduisant à une fonction (input_bramigraph()) def input_character(self, modifier, character, data) -> bool: """ Do what needs to be done for this braille modifier and character. :param modifier: bits field (see Keyboard.BrailleModifier) :param character: unicode char :param data: brut braille comb. for advanced treatment :return: True if command treated, otherwise False """ def input_bramigraph(self, modifier, bramigraph) -> bool: """ Do what needs to be done for this modifier and bramigraph. :param modifier: bits field (see Keyboard.BrailleModifier) :param bramigraph: braille function (see Keyboard.BrailleFunction) :return: True if command treated, otherwise False """ Clavier curseur routine L’appui sur une touche curseur routine appelée touche interactive dans b.note déclenche la fonction ci-dessous : def input_interactive(self, modifier, position, key_type) -> bool: """ Do what needs to be done for this modifier and cursor routine event. :param modifier: bits field (see Keyboard.BrailleModifier) :param position: index of key (based 1) :param key_type: see Keyboard.InteractiveKeyType :return: True if command treated, otherwise False """ Autres évènements Fonction Si l’application exploite le multi-tâche, elle peut avoir besoin de déclencher des fonctions qui seront prises en compte par le processus principal, ces évènement déclenchent la fonction ci-dessous : def input_function(self, *args, **kwargs) -> bool: """ Call when function is not treated by base class of this class. :param args[0]: The function id :param kwargs: :return: True if function treated. """ Pour déclencher une fonction, il suffit d’écrire : self._put_in_function_queue(FunctionId.FUNCTION_…) Timer Un événement timer tombe toutes les secondes def on_timer(self): """ Event each seconds :return: None """ Le rafraîchissement de la plage braille Une seul fonction permet d’afficher une ligne de texte sur l’afficheur braille def set_data_line(self): """ Construct the braille display line from document :return: None (self._braille_display.set_data_line is done) """ En général, cette fonction permet d’envoyer sur l’afficheur braille la ligne du document de l’application. Le codage de cette fonction consiste à construire 3 buffers de texte * Un buffer de texte alphanumérique (pour esyviewer notamment) * Un buffer de braille unicode décrivant les points fixes * Un buffer de braille unicode décrivant les points clignotants puis d’appeler self._braille_display.set_data_line avec ces 3 buffers comme paramètre. Objets standards Les menus Les menus sont gérés par 2 classes du dossier ui : * UiMenuBar La barre de menu ou un sous menu * UiMenuItem Un élément de menu terminal Un UiMenuBar est caractérisé par : 'name': le nom du sous menu, 'action': (None par défaut) Une fonction de l’application, 'ui_objects': Une liste décrivant son contenu, elle sera composée de UiMenubar et de UiMenuItem, 'is_root': (False par défaut) ce booléen permet de marquer l’élément racine de la description de menu, 'focused_object': 0 Un UiMenuItem est caractérisé par : 'name': le nom de l’élément de menu, 'shortcut_modifier': les modifieurs du raccourci clavier associé à cet élément, 'shortcut_key': la description de la touche de raccourci, 'action': Chaque élément de menu terminal est associé à une fonction de l’application nommé par convention def _exec_menu_nom_de_la_fonction(self), 'action_param': (None par défaut) Ce paramètre permet de définir des paramètres à passer lors du lancement de l’action, 'is_hide': (False par défaut) Masquage de l’élément de menu, Exemple de création d’un menu : def __create_menu(self): # Instantiate menu (A menu bar with 1 sub menu of 2 menu items and one menu item). return UiMenuBar( name=_("skeleton"), # Call on ESC bramigraph key is_root=True, menu_item_list=[ UiMenuBar( name=_("&group"), menu_item_list=[ UiMenuItem(name=_("&menu_1"), action=self._exec_menu_1), UiMenuItem(name=_("&menu_2"), action=self._exec_menu_2), ]), UiMenuItem(name=_("&say hello"), action=self._exec_say_hello), UiMenuItem(name=_("&about"), action=self._exec_about, shortcut_modifier=Keyboard.BrailleModifier.BRAILLE_FLAG_NONE, shortcut_key = Keyboard.BrailleFunction.BRAMIGRAPH_F1), ], ) Les boîtes de dialogue Eléments Les boîtes de dialogue sont gérées par les classes du dossier ui suivantes : * UiDialogBox La boîte de dialogue * UiCheckBox Une case à cocher * UiListBox Une liste * UiEditBox Une boite éditable * UiLabel Un texte non modifiable * UiButton Un bouton Boîtes de dialogue prédéfinies Des boîtes de dialogue standard sont déjà définies dans le but de globaliser les boîtes à usage général et d’alléger le code des applications. Elles correspondent aux classes suivantes : * UiMessageDialogBox Une boîte de dialogue composé d’un nom, d’un message et d’une liste de bouton, * UiInfoDialogBox Une boîte de dialogue d’information composée d’un message et d’un bouton Ok, Gestion du braille Le braille est géré par une classe globale b.noteApp.lou qui correspond à une instance de liblouis dans la langue en usage pour l’appareil. Les fonctions clés def to_dots_8(self, txt): """ Convert a string into an unicode braille string (8 dots) (x28nn chars). : param txt : (str) alphanumeric string of text : return : (str) unicode braille string (\u28xx...) """ Cette fonction permet de convertir un texte en une chaîne de caractères braille. C’est la seule fonction utile pour une application qui reste en braille informatique 8 points, elle permettra d’envoyer en ligne convertie à l’afficheur braille. Synthèse vocale b.note dispose d’un point d’entrée global pour activer la synthèse vocale def speak(text, lang_id=None, volume=None, speed=None, purge_before_speak=True): Pour une utilisation plus avancée de la synthèse vocale il faudra directement s’interfacer à la classe SpeechManager(). © 2022 - Eurobraille sa /