Ertza Documentation. Release Benoit Rapidel, ExMachina

Transcription

1 Ertza Documentation Release Benoit Rapidel, ExMachina October 05, 2016

2

3 Contents 1 Configuration files Configuration types Base configuration files Configuration predecence Classes Commands OSC commands Serial commands Profiles List profiles Load profile Unload profile Dump profile List profile options Set profile option Save profile Serial protocol Serial parameters Protocol Data-types (WIP) Ertza tools Ertza GUI Indices and tables 15 Python Module Index 17 i

4 ii

5 Ertza Documentation, Release Ertza is a python program providing a simple, yet powerful, gateway between motor drive and protocols such as OSC or DMX. It s designed to work on a BeagleBone Black with an ArmazCape on top. For ArmazCape schematics and PCB design, please refer to eisla-electronics repository. Ertza is usually embedded into Elias distro which is build using Yocto Project. Elias main layer can be found at meta-exm-core repository Ertza features: Communication with motor drive (via an extensible driver nodule interface) Currently only ModBus TCP is supported. A debug fake driver is also provided. Key events based on interrupts to expose basic actions or limit switches Remote control via multiple protocols. Currently OSC and a serial protocol are implemented Cascading configuration scheme Configuration managed through profiles that allow quick reconfiguration Temperature watcher Fan regulator Configurable LED system Contents: Contents 1

6 Ertza Documentation, Release Contents

7 CHAPTER 1 Configuration files Configuration system in ertza is based on a cascading system By default configuration files are placed under /etc/ertza. 1.1 Configuration types Three types of configurations files exists within ertza: Base configuration file: specify base parameters for ertza Most parameters are specified at startup and are never changed Variant configuration file: specify variant specific parametrs Usually stored under /etc/ertza/variants This allow to handle multiple variants of Armaz with different speeds, torque, etc... Profile configuration file: specify application related parameters Usually stored under /etc/ertza/profiles This give a easy way to configure Ertza for a specific application (see Profiles section) 1.2 Base configuration files There is three base configuration files: 1. default.conf stores default values for ertza 2. machine.conf stores machine specific values (mostly drive related values) 3. custom.conf stores modified values like the loaded profile They are loaded in sequence. This ensure that the default value for a parameter stored in default.conf will be overwritten if defined in machine.conf or custom.conf 1.3 Configuration predecence To guaranty the precedence between each configuration type, Ertza maintain a map where each configuration file has it s own priority: 1. variant.conf 2. profile.conf 3

8 Ertza Documentation, Release custom.conf 4. machine.conf 5. default.conf This ensure that none of the values defined in variant.conf could be overwritten and that the values defined in profile.conf takes precedence over others (except variant.conf). This is to prevent end-user to modify limit values fixed for the machine (i.e.: max_velocity of motor) 1.4 Classes exception ertza.configparser.nosectionerror(section) Bases: configparser.error Raised when no section matches a requested option. exception ertza.configparser.nooptionerror(option, section) Bases: configparser.error A requested option was not found. exception ertza.configparser.parsingerror(source=none, filename=none) Bases: configparser.error Raised when a configuration file does not follow legal syntax. filename Deprecated, use source. exception ertza.configparser.filenotfounderror(msg= ) Bases: ertza.configparser.configparsererror Raised when a config file cannot be found or read. exception ertza.configparser.varianterror(msg= ) Bases: ertza.configparser.configparsererror Raised when an error happens during a variant operation. exception ertza.configparser.profileerror(msg= ) Bases: ertza.configparser.configparsererror Raised when an error happens during a profile operation. class ertza.configparser.configparser(*args, **kwargs) Bases: ertza.configparser.abstractconfigparser ConfigParser provides config interface. Its handle cascading config files. load_config(config_file) Load config file appending to config_files. Parameters config_file The config file to load Raises FileNotFoundError if file doesn t exist load_profile(profile=none, **kwargs) Load profile file. If profile is not specified, load profile defined in config file with machine:profile. Store the loaded profile in config. 4 Chapter 1. Configuration files

9 Ertza Documentation, Release Parameters profile (str) The profile file to load Raises ProfileError if no profile is given and machine:profile doesn t exist in config load_variant(variant=none, **kwargs) Load a variant config file. If variant is not specified, load variant value defined in config file. Parameters variant (str) The variant config file to load Raises VariantError if a variant is already loaded 1.4. Classes 5

10 Ertza Documentation, Release Chapter 1. Configuration files

11 CHAPTER 2 Commands Commands defines a way for remotes to interact with ertza. They also defines the public API for the slave machimism. Commands are protocol dependant. This allow to customize behaviour and arguments required on a per-protocol basis. The two main protocols currently supported are OSC and a custom serial protocol. 2.1 OSC commands class ertza.commands.osc.configget(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Returns the value of SECTION:OPTION. This allow to verify the behaviour of the config. This behaviour can be changed by variant config or profile. class ertza.commands.osc.configprofileclearoption(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Clear an assigned option: class ertza.commands.osc.configprofiledump(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Dump profile content: /config/profile/dump/reply SECTION:OPTION VALUE The command always send a ok reply at the end of the dump: /config/profile/dump/ok done class ertza.commands.osc.configprofilelist(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Return a list of available profils: /config/profile/list/reply PROFILE The command always send a ok reply at the end of the dump: /config/profile/list/ok done class ertza.commands.osc.configprofilelistoptions(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Return a list of assignable options: /config/profile/list_options/reply SECTION:OPTION The command always send a ok reply at the end of the dump: /config/profile/list_options/ok done 7

12 Ertza Documentation, Release class ertza.commands.osc.configprofileload(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Load existing profile found in _PROFILE_PATH (usually /etc/ertza/profiles) class ertza.commands.osc.configprofilesave(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Save profile to a file in _PROFILE_PATH. If PROFILE is empty, overwrites the loaded profile class ertza.commands.osc.configprofileset(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Set value in profile (not in config) class ertza.commands.osc.configprofileunload(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Unload loaded profile (if any) class ertza.commands.osc.configsave(machine) Bases: ertza.commands.abstract_commands.unbufferedcommand, ertza.commands.osc_command.osccommand Save config to custom.conf including the loaded profile name class ertza.commands.osc.slavecommand(machine) Bases: ertza.commands.osc_command.osccommand Ensure machine is in slave mode. class ertza.commands.osc.slaveget(machine) Bases: slave.slavecommand, ertza.commands.abstract_commands.unbufferedcommand Received by a slave. 2.2 Serial commands 8 Chapter 2. Commands

13 CHAPTER 3 Profiles Profile system provides a quick way to store, load and modify parameters in ertza. It also ensure that critical parameters (like max_velocity) cannot be overwritten by user input Listed commands are given using OSC protocol but are also available through serial protocol 3.1 List profiles class ertza.commands.osc.configprofilelist(machine) Return a list of available profils: /config/profile/list/reply PROFILE The command always send a ok reply at the end of the dump: /config/profile/list/ok done 3.2 Load profile class ertza.commands.osc.configprofileload(machine) Load existing profile found in _PROFILE_PATH (usually /etc/ertza/profiles) 3.3 Unload profile class ertza.commands.osc.configprofileunload(machine) Unload loaded profile (if any) 3.4 Dump profile class ertza.commands.osc.configprofiledump(machine) Dump profile content: /config/profile/dump/reply SECTION:OPTION VALUE The command always send a ok reply at the end of the dump: /config/profile/dump/ok done 3.5 List profile options class ertza.commands.osc.configprofilelistoptions(machine) Return a list of assignable options: /config/profile/list_options/reply SECTION:OPTION 9

14 Ertza Documentation, Release The command always send a ok reply at the end of the dump: /config/profile/list_options/ok done 3.6 Set profile option class ertza.commands.osc.configprofileset(machine) Set value in profile (not in config) 3.7 Save profile class ertza.commands.osc.configprofilesave(machine) Save profile to a file in _PROFILE_PATH. If PROFILE is empty, overwrites the loaded profile 10 Chapter 3. Profiles

15 CHAPTER 4 Serial protocol The serial protocol implemented in ertza allow remote control through a serial link. 4.1 Serial parameters Baudrate: Parity: None Stop bits: Protocol Each serial packet have a strict syntax. The first 8 bytes are a constant fixed to ExmEisla. Next is two bytes defining the length of the packet. The following 16 bytes defines the serial number of the sender. For Eisla product range it is WWYYPPPPNNNN where: WW is the production week number in a ISO Format (1-53) YY is the production year PPPP is the part number (ARCP for ArmazCape) NNNN is the unit number produced during the week Next is the command itself. The command is formed by: Each part of a command is separated by a : An alias It is a text string (encoded in ASCII) defining the desired action. Sub levels can be specified by adding a. between levels i.e. config.get Zero or one or more argument Can be a string, an integer, a float or a boolean Finally all commands ends with \r\n This give the following format: ExmEislaLLWWYYPPPPNNalias.level:parameter:parameter\r\n i.e. b ExmEisla\x00\x370116ARCP0001config.get:machine.serialnumber\r\n The length must be parsed by the receiver to ensure that the packet is not corrupted. 11

16 Ertza Documentation, Release Data-types (WIP) ExmEisla protocol does not provides a way to transmit data types along with data. Therefore, all devices must know what data type is expected. Numeric data is transmitted little-endian. However, bytes are encoded with MSBit first. i.e. >>> 3 # is transmitted as b \x03\x00\x00\x00 For simplification, only the following data types are recognized String Strings are ASCII encoded text Integer Integers are signed 32-bit integers Float Floats are encoded using IEEE-754 using 32 bits Boolean Boolean are encoded using 8 bits (= 1 byte). 12 Chapter 4. Serial protocol

17 CHAPTER 5 Ertza tools To help configuration and debugging, the following tools are included under /tools 5.1 Ertza GUI Ertza GUI provides a GUI that allow to configure and control a motor block running ertza. It has been tested under Debian but as been developed with interoperability in mind. A port under Windows or OSX shouldn t be too difficult. It provides the following features: Auto detection of online motor blocks Instant control of motor blocks in all control modes Access to status data Configuration of motor blocks Profile handling system Remote logging of a motor block 13

18 Ertza Documentation, Release Screenshot 14 Chapter 5. Ertza tools

19 CHAPTER 6 Indices and tables genindex modindex search 15

20 Ertza Documentation, Release Chapter 6. Indices and tables

21 Python Module Index e ertza.commands.osc, 7 ertza.configparser, 4 17

22 Ertza Documentation, Release Python Module Index

23 Index C ConfigGet (class in ertza.commands.osc), 7 ConfigParser (class in ertza.configparser), 4 ConfigProfileClearOption (class in ertza.commands.osc), 7 ConfigProfileDump (class in ertza.commands.osc), 7 ConfigProfileList (class in ertza.commands.osc), 7 ConfigProfileListOptions (class in ertza.commands.osc), 7 ConfigProfileLoad (class in ertza.commands.osc), 7 ConfigProfileSave (class in ertza.commands.osc), 8 ConfigProfileSet (class in ertza.commands.osc), 8 ConfigProfileUnload (class in ertza.commands.osc), 8 ConfigSave (class in ertza.commands.osc), 8 E ertza.commands.osc (module), 7 ertza.configparser (module), 4 F filename (ertza.configparser.parsingerror attribute), 4 FileNotFoundError, 4 L load_config() (ertza.configparser.configparser method), 4 load_profile() (ertza.configparser.configparser method), 4 load_variant() (ertza.configparser.configparser method), 5 N NoOptionError, 4 NoSectionError, 4 P ParsingError, 4 ProfileError, 4 S SlaveCommand (class in ertza.commands.osc), 8 SlaveGet (class in ertza.commands.osc), 8 V VariantError, 4 19