The interactive Visualizer application is a great way to get familiar with the capabilities of the Sweep device. However, the visualizer does a fair bit of work behind the scenes to keep things running smoothly. When you write applications that interact with the Sweep device, you'll have to do a bit of management as well. Here are a few tips and guidelines to help you create more robust applications.

 

Ensure motor speed setting > 0Hz before sending "DS"

The sensor cannot stream data when it is stationary. If a stationary sensor receives a "Data Start - DS" command, it will respond with a receipt indicating a failure to start data acquisition because the sensor was stationary. The details of this receipt is outlined in the protocol spec. 

You can avoid parsing this kind of receipt if you just check that the motor speed setting is > 0Hz before starting data acquisition.

 

Query "Motor Ready - MZ" before "DS" or "MS"

Whenever the sweep changes motor speed, it performs a calibration routine to account for inconsistencies in encoder which helps the sweep produce accurate measurements. This calibration routine must be performed when the motor has stabilized at a constant speed. Therefore, the device waits a safe amount of time before performing the calibration. This routine occurs after:

• powering on the device
• after receiving any form of "Adjust Motor Speed - MS" command, regardless of the size of the adjustment (ie: even calling "MS" with the current  motor speed will still trigger a calibration)

During the process (stabilization + calibration routine), the LED on the face of the device will blink blue. Once the blue LED has stopped blinking, the calibration routine is complete and the motor is ready. This wait time also helps enforce that the motor speed has stabilized at the new setting before anything else.

Currently, the device cannot process certain types of commands before the calibration routine is complete. These types of commands include:

• Data Start - DS
• Adjust Motor Speed - MS

If the device cannot process a command, it should still return a receipt indicating a failure to carry out the command. The receipts use unique status byte codes to indicate various types of failures. The details of these codes are outlined in the protocol spec.

Now, here is the tip: You can avoid parsing and managing these edge cases, if you query the status before attempting to send a command like "DS" or "MS". Use the "Motor Ready - MZ" command to tell if the device is ready. The "MZ" command will indicate one of the following:

• Ready! This means that the calibration routine is complete, and that the motor speed has stabilized to its current setting. Sending a "DS" or "MS" command should work.
• Not Ready. Don't bother trying to send a "DS" or "MS" command now. You'll have to wait until the device is ready before those commands will yield a successful action. Visually this corresponds to when the blue LED stops blinking.

A simple while loop and a sleep function should handle this from a programmatic approach.

 

Be Aware that "Motor Speed Setting" means SETTING

Commands like "Adjust Motor Speed - MS" and "Motor Information - MI" deal with motor speed settings. There are 11 speed settings (0-10Hz), represented by aptly chosen codes ('00' - '10'). When you adjust the motor speed, you are changing the current speed setting. The device will then attempt to adjust speed to that new setting. This takes time (see section above on "Motor Ready - MZ"). If you query the motor speed using "Motor Information - MI", you'll get a response indicating the current speed setting, NOT the current speed.

For example, consider the following scenario:

• The device is stationary at 0Hz
• Program sends an "MS10\n" command to adjust motor speed setting to '10' (ie: 10Hz)
• Program immediately sends an "MI\n" command to query the current motor speed setting

The response to the "MI" command will indicate that the current motor speed setting is '10' (ie: 10Hz). Yet the actual motor speed is still adjusting and could be anywhere between 0Hz and 10Hz. Ie: the response indicates the current motor speed SETTING, not the current motor speed. You need to use "Motor Ready - MZ" to tell if the motor speed has stabilized to the current motor speed setting.

 

Be Careful Sending Back to Back Commands

The device should be capable of processing a few commands back to back, but sending it a string of commands in one burst over the wire can result it unexpected behavior or errors. For example, avoid sending a single burst that contains multiple commands... such as "MS05\nMI\nLR00\nLI\n". Or worse yet, a single burst with multiple of the same command such as "DX\nDX\nDX\nDX\n". 

Best practice involves waiting a few milliseconds between successive commands. For example, the sweep-sdk enforces that successive commands are sent no closer together than 2ms.

Most of the time device interaction involves checking a receipt before sending the next command anyways, so this isn't a large restriction on usability.

 

Be Aware of the First Partial Scan

Data acquisition involves a continuous stream of data blocks, each representing a single sensor reading. When the device receives a command to start data acquisition, it will begin the stream mid rotation. If you are only looking for complete 360 degree scans, disregard the incoming data blocks until you see a sync reading. If you are using the sweep-sdk, simply disregard the first scan as it is a partial scan.

 

Keep an Eye out for Invalid Scans

At lower speeds the device is particularly susceptible to rotational torque. The encoder looks for a long tick, and torquing on the device can cause the head to slow down with respect to the encoding ticks. This might cause the sensor to interpret the long tick as a sync reading, which it thinks is located at the 0 degree mark. During an intense jerk or torquing of the device, this can manifest as a cascade of miniature invalid scans comprised of a low quantity of entirely incorrect readings. The scanner will attempt to find the true long encoder tick, to re-establish a true zero mark. Keep this in mind if you see rapid succession of sync readings or relatively low point counts between successive sync readings.

 

Avoid Interfering with the Device During Calibration

It has already been mentioned that the device performs a calibration routine after powering on or after changing motor speed. The calibration routine itself is very brief, but it must assume that the motor is spinning at a constant speed. For this to work effectively, a longer mandatory grace period is enforced before the routine is initiated. This helps guarantee that the motor speed has stabilized before the calibration routine is performed.

If the device is bumped, torqued or jostled while the calibration routine is underway, the calibration may be affected. This can affect the accuracy of the readings. A good rule of thumb is to keep the device as stationary as possible until the blue LED stops blinking.