blob: 22514b7faf716a8da186a45f8d0f5327d7fe1b35 [file] [log] [blame]
# Lint as: python2, python3
# Copyright 2017 The Chromium OS Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
"""This module provides interface to control button motors."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
import collections
import logging
import os
import time
from . import chameleon_common # pylint: disable=W0611
from chameleond.utils import chameleon_io as io
from six.moves import range
Holds bit offsets for motor ports.
Currently all motors use the same I/O expander.
If some motor needs to use another I/O expander, or some ports of a
motor need to use another I/O expander, index needs to be saved in
MotorPorts too.
MotorPorts = collections.namedtuple(
'MotorPorts', ['step', 'direction', 'enable'])
--------------- All the way to the top
{} |
{} | num_pulses_reset
{} |
{} V
{} -------- Reset position
{} ^
{} | num_pulses_move
{} V
{} -------- Touch position
| | Button
Motor parameter:
num_pulses_reset: Number of pulses to drive step motor to reset position
starting from all the way to the top.
num_pulses_move: Number of pulses to drive step motor to touch position from
reset position.
period_ms: Duration of each pulse in ms.
MotorParams = collections.namedtuple(
'MotorParams', ['num_pulses_reset', 'num_pulses_move', 'period_ms'])
class ButtonFunction(object):
"""Button functions that motor touch/release."""
CALL = 'Call'
HANG_UP = 'Hang Up'
MUTE = 'Mute'
VOL_UP = 'Vol Up'
VOL_DOWN = 'Vol Down'
class MotorBoardException(Exception):
"""Errors in MotorBoard."""
class MotorBoardNotExistException(MotorBoardException):
"""Error that motor board does not exist."""
class MotorBoard(object):
"""Controls button motor through motor board.
A motor has three ports: Step, Direction, Enable.
There are five motors to control on motor board.
This class provides the interface to control these ports.
The ports are controlled through an I/O expander on I2C bus 3 address 0x23.
I/O expander: address 0x23
bit offset 15 14 13 12 11 10 9 8
name p17 p16 p15 p14 p13 p12 p11 p10
bit offset 7 6 5 4 3 2 1 0
name p07 p06 p05 p04 p03 p02 p01 p00
Common: Microstep resolution
Name name bit offset
MS1 p01 1
MS2 p02 2
MS3 p03 3
Motor Function port name bit offset
0 Call step p04 4
dir p00 0
enable p05 5
1 Hangup step p06 6
dir p00 0
enable p07 7
2 Mute step p10 8
dir p00 0
enable p11 9
3 Vol Up step p12 10
dir p00 0
enable p13 11
4 Vol Down step p14 12
dir p00 0
enable p15 13
# Mapping from motor function to ports.
ButtonFunction.CALL: MotorPorts(4, 0, 5),
ButtonFunction.HANG_UP: MotorPorts(6, 0, 7),
ButtonFunction.MUTE: MotorPorts(8, 0, 9),
ButtonFunction.VOL_UP: MotorPorts(10, 0, 11),
ButtonFunction.VOL_DOWN: MotorPorts(12, 0, 13)}
# TODO(cychiang) Tune the duration and parameters.
'Atrus': {
ButtonFunction.CALL: MotorParams(200, 250, 1),
ButtonFunction.HANG_UP: MotorParams(200, 250, 1),
ButtonFunction.MUTE: MotorParams(200, 250, 1),
ButtonFunction.VOL_UP: MotorParams(200, 200, 1),
ButtonFunction.VOL_DOWN: MotorParams(200, 200, 1),
'Jabra': {
ButtonFunction.CALL: MotorParams(350, 250, 1),
ButtonFunction.HANG_UP: MotorParams(350, 250, 1),
ButtonFunction.MUTE: MotorParams(350, 250, 1),
ButtonFunction.VOL_UP: MotorParams(350, 220, 1),
ButtonFunction.VOL_DOWN: MotorParams(350, 220, 1),
_MODEL_TAG_PATH = '/etc/default/motor_model'
def __init__(self, i2c_bus):
"""Constructs a MotorBoard.
i2c_bus: The I2cBus object.
self._i2c_bus = i2c_bus
self._motor_io = io.IoExpander(self._i2c_bus,
self._motors = {}
def IsDetected(self):
"""Returns if the device can be detected."""
if self._motor_io.IsDetected():
return True
else:'Can not access I2c slave on motor board. '
'Assume it is not connected')
return False
def InitDevice(self):
"""Runs the initialization sequence for the motor board.
MotorBoardException: If motor board can not be initialized.
model_name = self._GetModelName()'Init motor board for model: %s', model_name)
self._CreateMotors(model_name)'MotorBoard initialized')
def Reset(self):
"""Resets motor boards by releasing button and resetting port directions."""
for func, motor in list(self._motors.items()):'Reset motor for %s function', func)
def _GetModelName(self):
"""Gets model name for this motor board.
A string for model name.
If model tag path does not exist or it contains unexpected model name.
if not os.path.exists(self._MODEL_TAG_PATH):
raise MotorBoardException(
'Model path does not exist: %s' % self._MODEL_TAG_PATH)
with open(self._MODEL_TAG_PATH) as f:
model_name = f.readline().strip()
if model_name not in self._MODEL_PARAMS_MAP:
raise MotorBoardException('Model name not expected: %s' % model_name)
return model_name
def _ResetPorts(self):
"""Resets all ports on I/O expander to input direction.
The voltage level of all the ports are determined by their pull-up
or pull-down circuits.
def _CreateMotors(self, model_name):
"""Creates motors.
model_name: A key in self._MODEL_PARAMS_MAP.
if model_name not in self._MODEL_PARAMS_MAP:
raise MotorBoardException('Unexpected model name %s' % model_name)
model_map = self._MODEL_PARAMS_MAP[model_name]
for func, params in list(model_map.items()):
ports = self._MOTOR_PORT_MAP[func]
self._motors[func] = Motor(self._motor_io, ports, params)
def _CheckFunction(self, func):
"""Check if a button function is supported on this motor board.
func: Button function for this motor. Defined in ButtonFunction.
MotorBoardException if func is not supported on this motor board.
if func not in self._motors:
raise MotorBoardException('Button function %s not suported' % func)
def Touch(self, func):
"""Let one of the motor moves to touch a button.
func: Button function for this motor. Defined in ButtonFunction.
def Release(self, func):
"""Let one of the motor release button.
func: Button function for this motor. Defined in ButtonFunction.
class _MotorState(object):
"""Motor states."""
RELEASED = 'Released'
TOUCHED = 'Touched'
class _MotorDirection(object):
"""Motor moving direction."""
UP = 'Up'
DOWN = 'Down'
class MotorError(Exception):
"""Error in Motor."""
class Motor(object):
"""Class to control one motor."""
def __init__(self, motor_io, motor_ports, params):
"""Initializes one Motor.
motor_io: A IoExpander object.
motor_ports: A MotorPorts for port bit offset.
params: A MotorParams namedtuple.
self._motor_io = motor_io
self._ports = motor_ports
self._params = params
# TODO(cychiang) See if this assumption is true, or add a mechanism
# to reset the motor state when init.
self._state = _MotorState.RELEASED
def Reset(self):
"""Controls the motor to reset position."""
# Moves all the way to the top.
# Moves down to reset position.
self._state = _MotorState.RELEASED
def Touch(self):
"""Controls the motor to touch the button."""
if self._state == _MotorState.TOUCHED:
self._state = _MotorState.TOUCHED
def Release(self):
"""Controls the motor to release the button."""
if self._state == _MotorState.RELEASED:
self._state = _MotorState.RELEASED
def _SetDirection(self, direction):
"""Sets motor movement direction.
direction: A direction defined in _MotorDirection.
MotorError: Unexpected direction.
# Up: set port to 0.
# Down: set port to 1.
value = None
if direction == _MotorDirection.UP:
value = 0
elif direction == _MotorDirection.DOWN:
value = 1
raise MotorError('Unexpected direction: %s' % direction)
offset = self._ports.direction
self._motor_io.SetBit(offset, value)
def _Enable(self, enable):
"""Enables/Disables motor.
Note this function does not start motor movement. It just turns on motor
or let it sleep for power saving.
enable: True to enable; False to disable.
# TODO(cychiang) Find out whether this port works or not.
# Enable: set port to 0.
# Disable: set port to 1.
value = 0 if enable else 1
offset = self._ports.enable
self._motor_io.SetBit(offset, value)
def _Move(self, num_pulse):
"""Moves motor by driving pulses on step port.
Drives num_pulse pulses with each pulse period_ms duration in ms.
num_pulse: Number of pulse to drive motor.
offset = self._ports.step
half_period_sec = self._params.period_ms / 2 * 0.001
for _ in range(num_pulse):
self._motor_io.SetBit(offset, self._MOTOR_PULSE_LOW)
self._motor_io.SetBit(offset, self._MOTOR_PULSE_HIGH)