Prise en main
=============

Le matériel
-----------

- une **carte ratbot_controller**, seule sur la table ou montée dans un
  robot ;
- son **alimentation** : la batterie du robot, ou une alimentation de
  laboratoire réglée sur la tension de la batterie ;
- une **sonde ST-LINK** (STLINK-V3 ou équivalent), reliée au connecteur
  **SWD** de la carte ;
- un ordinateur sous Linux, avec **STM32CubeIDE**.

.. warning::

   Si la carte est dans un robot, **ses roues doivent pouvoir tourner
   librement** (robot posé sur une cale) : un programme de TP ne contient
   aucune des sécurités du firmware RatBot.

Le microcontrôleur
------------------

La carte porte un **STM32H750VBT6** : un cœur Cortex-M7 en boîtier LQFP100.
Sa mémoire flash interne est petite, **128 Kio**. C'est là que vont les
programmes des TP de la première partie, comme dans tout projet
STM32CubeIDE.

Au démarrage, sans réglage particulier, le microcontrôleur fonctionne sur son
**oscillateur interne HSI à 64 MHz**. Les TP de la première partie gardent
cette horloge : aucun réglage d'horloge n'est nécessaire.

Installer STM32CubeIDE
----------------------

STM32CubeIDE réunit trois outils : **CubeMX**, qui configure les broches et
les périphériques puis génère le code d'initialisation ; un **éditeur et
compilateur C** ; et le **débogueur**, qui programme la carte par la sonde
ST-LINK.

Le télécharger sur le site de ST (un compte gratuit est nécessaire), puis
l'installer en suivant ses instructions. Au premier lancement, il télécharge
le paquet de support des STM32H7 : prévoir un accès à Internet.

.. _etat-ratbot:

Remettre la carte en état RatBot
--------------------------------

Un programme de TP s'écrit au début de la flash interne, **à la place du
chargeur d'amorçage** (*bootloader*) de RatBot. Après un TP, la carte ne
démarre donc plus le firmware du robot, même s'il est toujours présent dans
la mémoire flash externe. Pour la remettre en état, depuis la racine du dépôt
RatBot, sonde branchée :

.. code-block:: bash

   # 1. le chargeur d'amorçage, dans la flash interne
   make -C firmware/ratbot_bootloader flash

   # 2. le firmware du robot, dans la flash externe (QSPI)
   STM32_Programmer_CLI -c port=SWD mode=UR \
     -el <chemin>/STM32H7xx_W25Q128_WeActStudio.stldr \
     -d firmware/ratbot_firmware_card/build/uROSProjet.bin 0x90000000 -v

   # 3. redémarrer la carte
   STM32_Programmer_CLI -c port=SWD mode=HOTPLUG -rst

L'étape 2 n'est utile que si la flash externe a été effacée ou réécrite : un
TP de la première partie n'y touche pas ; ceux qui programment la flash
externe (partie 2, TP 7 et 8, et partie 3) la remplacent. Le fichier ``.stldr`` et le détail de la procédure sont dans la
documentation développeur (page *Bootloader*).

.. warning::

   Toujours finir par ``-rst``, **jamais** ``-hardRst`` : ce dernier laisse
   la flash externe dans un état que le chargeur d'amorçage ne sait pas
   reprendre.