scripts/flashing/efr32_firmware_utils.py

   1 #!/usr/bin/env python3
   2 # Copyright (c) 2020 Project CHIP Authors
   3 #
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 # http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15 """Flash an EFR32 device.
  16
  17 This is layered so that a caller can perform individual operations
  18 through an `Flasher` instance, or operations according to a command line.
  19 For `Flasher`, see the class documentation. For the parse_command()
  20 interface or standalone execution:
  21
  22 usage: efr32_firmware_utils.py [-h] [--verbose] [--erase] [--application FILE]
  23                                [--verify_application] [--reset] [--skip_reset]
  24                                [--commander FILE] [--device DEVICE]
  25                                [--serialno SERIAL]
  26
  27 Flash EFR32 device
  28
  29 optional arguments:
  30   -h, --help            show this help message and exit
  31
  32 configuration:
  33   --verbose, -v         Report more verbosely
  34   --commander FILE      File name of the commander executable
  35   --device DEVICE, -d DEVICE
  36                         Device family or platform to target
  37   --serialno SERIAL, -s SERIAL
  38                         Serial number of device to flash
  39
  40 operations:
  41   --erase               Erase device
  42   --application FILE    Flash an image
  43   --verify_application, --verify-application
  44                         Verify the image after flashing
  45   --reset               Reset device after flashing
  46   --skip_reset, --skip-reset
  47                         Do not reset device after flashing
  48 """
  49
  50 import sys
  51
  52 import firmware_utils
  53
  54 # Additional options that can be use to configure an `Flasher`
  55 # object (as dictionary keys) and/or passed as command line options.
  56 EFR32_OPTIONS = {
  57     # Configuration options define properties used in flashing operations.
  58     'configuration': {
  59         # Tool configuration options.
  60         'commander': {
  61             'help': 'File name of the commander executable',
  62             'default': 'commander',
  63             'argparse': {
  64                 'metavar': 'FILE'
  65             },
  66             'verify': ['{commander}', '--version'],
  67             'error':
  68                 """\
  69                 Unable to execute {commander}.
  70
  71                 Please ensure that this tool is installed and
  72                 available. See the EFR32 example README for
  73                 installation instructions.
  74
  75                 """,
  76         },
  77         'device': {
  78             'help': 'Device family or platform to target',
  79             'default': 'EFR32',
  80             'alias': ['-d'],
  81             'argparse': {
  82                 'metavar': 'DEVICE'
  83             },
  84         },
  85         'serialno': {
  86             'help': 'Serial number of device to flash',
  87             'default': None,
  88             'alias': ['-s'],
  89             'argparse': {
  90                 'metavar': 'SERIAL'
  91             },
  92         },
  93     },
  94 }
  95
  96
  97 class Flasher(firmware_utils.Flasher):
  98     """Manage efr32 flashing."""
  99
 100     def __init__(self, **options):
 101         super().__init__(platform='EFR32', module=__name__, **options)
 102         self.define_options(EFR32_OPTIONS)
 103
 104     # Common command line arguments for commander device subcommands.
 105     DEVICE_ARGUMENTS = [{'optional': 'serialno'}, {'optional': 'device'}]
 106
 107     def erase(self):
 108         """Perform `commander device masserase`."""
 109         return self.run_tool(
 110             'commander', ['device', 'masserase', self.DEVICE_ARGUMENTS],
 111             name='Erase device')
 112
 113     def verify(self, image):
 114         """Verify image."""
 115         return self.run_tool(
 116             'commander',
 117             ['verify', self.DEVICE_ARGUMENTS, image],
 118             name='Verify',
 119             pass_message='Verified',
 120             fail_message='Not verified',
 121             fail_level=2)
 122
 123     def flash(self, image):
 124         """Flash image."""
 125         return self.run_tool(
 126             'commander',
 127             ['flash', self.DEVICE_ARGUMENTS, image],
 128             name='Flash')
 129
 130     def reset(self):
 131         """Reset the device."""
 132         return self.run_tool(
 133                 'commander',
 134                 ['device', 'reset', self.DEVICE_ARGUMENTS],
 135                 name='Reset')
 136
 137     def actions(self):
 138         """Perform actions on the device according to self.option."""
 139         self.log(3, 'Options:', self.option)
 140
 141         if self.option.erase:
 142             if self.erase().err:
 143                 return self
 144
 145         application = self.optional_file(self.option.application)
 146         if application:
 147             if self.flash(application).err:
 148                 return self
 149             if self.option.verify_application:
 150                 if self.verify(application).err:
 151                     return self
 152             if self.option.reset is None:
 153                 self.option.reset = True
 154
 155         if self.option.reset:
 156             if self.reset().err:
 157                 return self
 158
 159         return self
 160
 161
 162 if __name__ == '__main__':
 163     sys.exit(Flasher().flash_command(sys.argv))