File : motor.ads

--                              -*- Mode: Ada -*-
-- Filename        : motor.ads
-- Description     : All you need to operate the motor
-- Author          : Christfried Webers
-- Created On      : Mon Nov  1 15:26:16 1999
-- Last Modified By: .
-- Last Modified On: .
-- Update Count    : 0
-- Status          : Experimental
----------------------------------------------------------------------

-- The motor is initially not moving. The inner state is set to
--      LinearVelocity      := 0.0;
--      AngularVelocity     := 0.0;
--      LinearAcceleration  := 1.0;
--      AngularAcceleration := 1.0;
--      LinearTorque        := 1.0;
--      AngularTorque       := 1.0;
--
-- In order to drive the robot, the linear and angular velocity has
-- to be set to a value other than 0.0
--
-- LinearVelocity  > 0.0 --> move forward
-- LinearVelocity  < 0.0 --> move backward
-- AngularVelocity > 0.0 --> rotate left
-- AngularVelocity < 0.0 --> rotate right
--
-- Commands to the motor are stored and as
-- soon as the acknowledgement from the last
-- motor command is received from the robot,
-- the most recent command is send as next.
-- The user task is never blocking, but some
-- motor commands might get lost.
-- In order to synchronize external motor commands
-- and the robot, commands should be followed
-- by an explicit wait for the acknowledgement.

-- Emergency stops
-- In order to stop the robot very fast, two steps
-- are necessary for both linear and angular axes:
-- 1. Set the acceleration to a very high value
-- 2. Set the velocity to 0.0
-- If only the velocity is set to 0.0 the robot will decrease
-- the current velocity with the current set acceleration
-- which might take much longer than expected (and damage
-- whatever the robot is heading for!)

with Ada.Real_Time; use Ada.Real_Time;

with Metrics; use Metrics;

package Motor is

   ----------------------------------------------------------------
   --
   -- Types
   --
   ----------------------------------------------------------------

   type Status is record
      LinearPosition     : mm;
      LinearVelocity     : LinVel;
      LinearAcceleration : LinAcc;
      LinearTorque       : LinTorque;

      AngularPosition     : Degrees;
      AngularVelocity     : AngVel;
      AngularAcceleration : AngAcc;
      AngularTorque       : AngTorque;

      Timestamp : Time;
   end record;

   ----------------------------------------------------------------
   --
   -- Init and Shutdown
   --
   ----------------------------------------------------------------

   procedure Init;        -- There should be exactly ONE
   procedure Shutdown;    -- Init and Shutdown

   ----------------------------------------------------------------
   --
   -- Reading data from the motor
   --
   ----------------------------------------------------------------

   procedure GetCurrentStatus (MotorStatus : out Status);
   -- potentialy blocking if no motor data have been received at all

   procedure WaitForNewData;
   -- potentially blocking until new motor data arrive

   ----------------------------------------------------------------
   --
   -- Sending commands to the motor
   --
   ----------------------------------------------------------------
   procedure SetLinearVelocity (Velocity : LinVel);
   procedure SetAngularVelocity (Velocity : AngVel);

   procedure SetLinearAcceleration (Acceleration : LinAcc);
   procedure SetAngularAcceleration (Acceleration : AngAcc);

   procedure SetLinearTorque (Torque : LinTorque);
   procedure SetAngularTorque (Torque : AngTorque);

   procedure WaitForLinearCommandAck;
   -- block until the command to the linear axis is acknowledged

   procedure WaitForAngularCommandAck;
   -- block until the command to the angular axis is acknowledged

end Motor;