b.note v3.0.0 Manuel du développeur (2024-06-25) ________________ 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 Installation d’un dossier de développement 6 Développement sur b.note sans PycharmPE 7 Développement Sur PC avec PyCharmPE (Professional Edition) 7 Installation 7 Activation de la licence d’essai 8 Configuration du ‘Python Interpreter’ 8 Modification des packages de bnote 14 Gestion des packages python 14 Gestion des librairies linux 14 Réalisation et exécution d’un update de bnote 14 Exécution d’un update de bnote 15 Structure de l’application 16 L’application 16 Les événements clavier 16 Clavier de commande 16 Clavier braille 16 Clavier curseur routine 17 Autres évènements 17 Fonction 17 Timer 18 Le rafraîchissement de la plage braille 18 Objets standards 18 Les menus 18 Les boîtes de dialogue 19 Eléments 19 Boîtes de dialogue prédéfinies 20 Gestion du braille 20 Les fonctions clés 20 Synthèse vocale 20 ________________ 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 Dans le menu préférence dans la section interface utilisateur basculer l’option mode développeur sur oui. ou 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. Installation d’un dossier de développement Pour créer un environnement de développement indépendant de l’application bnote installée sur l’appareil un dossier develop/ est déjà créé sur la sd. Il contient un fichier .tar.gz contenant les sources de l’application bnote. pi@raspberrypi:~/develop $tar -xvf bnote-3.0.0.tar.gz pi@raspberrypi:~/develop $mv bnote-3.0.0 bnote pi@raspberrypi:~/develop $cd bnote pi@raspberrypi:~/develop/bnote $ sh ./setup.sh Développement sur b.note sans PycharmPE Une fois l’installation des sources et de l’environnement virtuel dans le dossier develop/bnote, il est possible de modifier les fichiers souces (.py) de b.note soit localement en ssh avec nano par exemple puis de lancer l’application manuellement. Arrêter le service de lancement de l’application : pi@raspberrypi:~ $sudo systemctl stop bnote.service Lancer manuellement l’application : pi@raspberrypi:~/develop/bnote $ source venv/bin/activate (venv)pi@raspberrypi:~/develop/bnote $python3 __main__.py ou (venv)pi@raspberrypi:~/develop/bnote $python3 __main_debug__.py Cette seconde méthode à l’avantage de rendre en ssh les traces de l’application visibles sur la console. Pour deactiver environnement virtuel python : (venv)pi@raspberrypi:~/develop/bnote $ deactivate 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 menu File>Settings, puis ouvrir Project:bnote>Python interpreter puis cliquer sur Add interpreter>on SSH renseigner l’adresse ip et le nom d’utilisateur (pi) Cliquer sur Next puis renseigner le mot de passe (euroberry) cliquer sur next, pycharm execute alors un test de connexion ________________ Cliquer sur next, puis cocher le bouton existing et définir le VirtualEnv Environnement sur /home/pi/develop/bnote/venv/bin/python3 Cliquer sur le dossier de Sync folders pour définir l’emplacement où les sources seront synchronisées avec Pycharm Cliquer sur ok puis sur create Une fois ces opérations réaliser, vous pouvez faire clic droit sur le dossier bnote racine du projet puis choisir Deployment>Upload to … pour synchroniser les sources de votre dossier de développement de bnote avec celles de pycharm. Vous pouvez ensuite lancer bnote_start.py depuis pycharm. Pour plus d’information consulter le lien suivant : https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html ________________ Modification des packages de bnote Gestion des packages python En ssh sur le bnote, depuis votre dossier de développement, vous pourrez taper: pi@raspberrypi:~/develop/bnote $ source venv/bin/activate (venv)pi@raspberrypi:~/develop/bnote $pip install mon_package Pour récupérer le package et ses dépendances vous pouvez utiliser les commandes suivantes: pi@raspberrypi:~/develop/bnote $mkdir -p /tmp/packages pi@raspberrypi:~/develop/bnote $pip download --dest /tmp/packages requests Vous pourrez alors le télécharger et l’inclure dans le dossier whl/ de votre update et ajouter son nom et sa version dans pyproject.toml de votre projet bnote. pour retirer un package python. pi@raspberrypi:~/develop/bnote $pip uninstall mon_package Gestion des librairies linux En ssh sur le bnote, depuis votre dossier de développement, vous pourrez taper: pi@raspberrypi:~/develop/bnote $sudo apt install ma_librairie pour ajouter une librairie. pi@raspberrypi:~/develop/bnote $sudo apt remove ma_librairie pour retirer une librairie. Lorsque vous réaliserez l’update, il vous faudra tenir compte des changements de librairie en mettant à jour le fichier libraries.txt. Chacune des commandes de ce fichier sera exécutée lors de l’installation de la nouvelle version de l’application. Une erreur durant ces exécution se soldera par un échec de l’installation de la version. Ce fichier ne cessera de grandir au fil des mises à jour. Réalisation et exécution d’un update de bnote En ssh sur le develop/bnote, depuis votre dossier de développement taper: pi@raspberrypi:~/develop/bnote $ sh ./generate.sh Cela générera un fichier bnote-....whl.zip au nom de la version de bnote définie dans pyproject.toml. Exécution d’un update de bnote C’est le fichier bnote…whl.zip qui permettra l’installation de l’application. Il suffira de le copier sur le bnote cible et de l’exécuter depuis l’explorateur de fichier de bnote. La nouvelle version sera installée dans le dossier all_bnotes avec son propre environnement virtuel. Il est donc possible de faire cohabiter plusieurs versions de bnote et de choisir celle qui sera lancée au démarrage. ________________ 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(). © 2024 - Eurobraille sa /