Configure Buffer

Usage

status = flex_configure_buffer(u8 boardID, u8 buffer, u8 resource, u16 bufferType, i32 buffersize, u32 totalPoints, u16 oldDataStop, f64 requestedInterval, f64* actualInterval);

Tip  Refer to the Remarks section for information about how the behavior of this function differs between controllers.

Purpose

Configures a buffer for use in buffered operations.

Parameters

Parameter Discussion

buffer is the buffer to configure. Valid buffer numbers are 1 through 255 (0x01 through 0xFF).

resource is the axis or vector space to associate with the specified buffer.

bufferType specifies the type of data in the buffer.

Following is detailed information about each of the buffer types:

NIMC_GENERAL_PURPOSE_INPUTNIMC_GENERAL_PURPOSE_OUTPUT

The general-purpose input and output buffer types allow you to allocate a buffer of memory on the NI motion controller for your own use. You can freely read from and write to the buffer from the host computer or from onboard programs.

The direction of a buffer is from the point of view of the host computer. An output buffer is typically written to by a program on the host computer and read from by an onboard program running on the NI motion controller. An input buffer is typically read from by a program on the host computer and written to by an onboard program running on the NI motion controller, as shown in the following figure.

For example, you can configure a 300-point output buffer and fill it with position, velocity, and acceleration values for a sequence of 100 moves. You also can write an onboard program that reads values from the buffer and places them in onboard variables. Then, a sequence of Load Target Position, Load Velocity and Load Acceleration/Deceleration functions can be executed, using the onboard variables as the source of their data.

As another example, you can configure an input buffer to hold analog input values. If you want to record the value of an analog input every time a particular digital input changes state, you can write an onboard program to wait for the digital input to change state, at which time you read the analog input and write the value to the buffer with the Write Buffer function. This action can be done in a loop in your onboard program. When the operation is complete, or even while the buffer is being filled with analog input values, a program running on the host computer can read the values from the buffer with the Read Buffer function. For these two buffer types, the resource and requestedInterval parameters are ignored.

NIMC_POSITION_DATA

This buffer type allows you to specify a sequence of one, two, or three-dimensional position data points to the NI motion controller. To specify two or three-dimensional position data, the resource parameter must be a vector space. The data is interpreted as absolute or relative contouring data depending on the value of the operation mode set through the Set Operation Mode function.

After you configure an axis or vector space for absolute or relative contouring in the Set Operation Mode function, and write the contouring data to the buffer with the Write Buffer function, you start the contouring operation by calling the Start Motion function. The NI motion controller processes the contouring data by splining between successive points. The requestedInterval parameter indicates the time between points in milliseconds. You are responsible for providing the points in a way that results in the specified acceleration, velocity and deceleration.

Note  If you are running a contoured move with a stepper axis, it is possible that the contour velocity exceeds the maximum step rate of the controller. In this case, the controller kills the axis and sets the following error status to true. Refer to the Specifications section of your controller user manual for the maximum step rate of your controller.

It is important to realize that all contoured moves are relative, meaning motion starts from the position of the axis or axes at the time the contouring move is started. Absolute contouring and relative contouring refer to the way the contouring data is interpreted. Absolute contouring data indicates the absolute position at each time interval, where the starting position is considered to be 0. Relative contouring data indicates incremental position differences between contouring points. The following two examples result in the same move taking place.

Absolute Contouring
1     3     6     10     14     18     22     25     27     28

Relative Contouring
1     2     3     4     4     4     4     3     2     1

If the axis was at position 0 to start with, it would end up at position 28 in both cases. If the axis was at position 10 to start with, it would end up at position 38 in both cases.

Choose the appropriate mode depending upon the kind of data you have or wish to provide. One benefit of the relative contouring mode is that you can specify multiple identical moves in the same direction with the same data. For example, the two-dimensional contour move shown in the following figure would be possible with 5 iterations of a relative contouring buffer, where totalPoints = five times the bufferSize, but would not be possible with absolute contouring data unless you provided five times as much data.

NIMC_BREAKPOINT_DATA

This buffer type allows you to specify a sequence of one-dimensional breakpoint position data points to send to the NI motion controller. The data is interpreted as absolute or relative depending on the value of the enable mode set through the Configure Breakpoint function.

After you configure an axis to include breakpoints and write the breakpoint data to the buffer with the Write Buffer function, you add the breakpoint by calling Configure Breakpoint.

NIMC_HIGH-SPEED_CAPTURE_READBACK

This buffer type allows you to specify a sequence of one-dimensional high-speed capture data points to send to the NI motion controller. This buffer is treated similarly to a general purpose output buffer, and you can freely read from the buffer from the host computer or from onboard programs. After you configure a buffer to contain high-speed capture data points and configure an axis to read the high-speed capture points from the buffer with the Configure High-Speed Capture function, you read the high-speed capture data by calling Read Buffer.

NIMC_CAMMING_POSITION

This buffer type allows you to specify a list of slave axis positions that will be used to calculate the camming profile. After you configure and write the slave axis position data, you can enable camming for a single axis or for multiple axes.

bufferSize is the size of the buffer in 32-bit data. If you configure a buffer for a three axis vector space with 1,000 3-dimensional points, the size of the buffer would be 3,000. For more information, refer to the NI 73xx Controller Considerations section of this function description.

totalPoints specifies the number of points that must be used or filled before the operation is complete. In most cases a value of bufferSize is appropriate. Valid values for totalPoints range from 1 to 2³²–1, inclusive. If totalPoints is greater than bufferSize, then read and write operations automatically wrap around to the beginning of the buffer.

Note  If you set totalPoints to 232-1, the buffer will run until the move is stopped, or the last counter data is written. Refer to Write Buffer for information about writing data to a buffer.

oldDataStop indicates to the motion controller if to stop reading from the buffer or writing to the buffer when old data is encountered. This is only relevant when totalPoints is greater than bufferSize. In the output case, such as contouring, when oldDataStop is true, and totalPoints is greater than bufferSize, you must write new data to the buffer before the motion controller finishes the buffer and starts over at the beginning. Likewise, for an input buffer, if the controller (or an onboard program running on the controller) is writing data to the buffer, such as buffered high-speed capture data, you must read data out of the buffer before the controller wraps around and writes new data on top of the old data.

If you set oldDataStop to false, the motion controller does not enforce the old data stop condition, and simply writes data to or reads data from the buffer as needed.
Range: True (1) or False (0)

requestedInterval specifies the requested time in milliseconds between contouring data points. interval is valid for only a bufferType of NIMC_POSITION_DATA, NIMC_BREAKPOINT_DATA, or NIMC_HIGH-SPEED_CAPTURE_READBACK.

The controller uses the closest legal value that is greater than or equal to the requested value for interval. Legal values for interval must be even multiples of the PID rate. See actualInterval for more information.

When used with NIMC_BREAKPOINT_DATA or NIMC_HIGH-SPEED_CAPTURE_READBACK, requestedInterval indicates how often, in milliseconds, the onboard data is updated from the hardware, and the value is a whole number.

actualInterval is the interval of time in milliseconds that the controller uses between successive points in the buffer. actualInterval may or may not be the same as the requestedInterval. For example, if the requestedInterval is physically impossible, then a different value is used. This value is represented as actualInterval.

For NIMC_BREAKPOINT_DATA or NIMC_HIGH-SPEED_CAPTURE_READBACK,

Using This Function

After a buffer has been configured, you can write to the buffer with the Write Buffer function and read from the buffer with the Read Buffer function.

A contour operation that uses a buffer is initiated when the Start Motion function is called. You check the state of the buffer with the Check Buffer function to determine how many points have been read from the buffer or written to the buffer by the NI motion controller.

After a buffered operation is completed, it is important to clear the buffer by calling the Clear Buffer function. Otherwise, the memory allocated for the buffer in the onboard RAM is not available for other uses, such as the allocation of another buffer.

A buffer cannot be reconfigured or cleared while the buffer is in use. An NIMC_bufferInUseError is generated in such a case.

A buffer can only be used by one resource at a time. Multiple resources can be associated with a single buffer, but only one resource can use that buffer at any given time. Likewise, a single resource can make use of many buffers, but for buffers of the same type, only one of them can be associated with that resource at a given time. Refer to the NI 73xx Controller Considerations section of this function description for more information.

Note  Configuring and clearing buffers is a processor-intensive operation on the NI motion controller that requires the allocation and de-allocation of memory. Configure and clear buffers only when motors are stopped and onboard programs are not running.

Remarks

This section includes information about how the behavior of this function differs among the controllers that support it.

NI 73xx Controller Considerations

The following list includes considerations you must make when you are using this function with a 73xx motion controller:

• Using input vectors and return vectors with the Read Buffer and Write Buffer functions, you can write to and read from the buffer with data stored in onboard variables. You must limit the number of points to read or write, because there are only 120 onboard variables. Data is read from or written to onboard variables sequentially starting at the variable specified by the inputVector or returnVector in the Write Buffer function or Read Buffer function.

  Specify a bufferSize of 0 to associate a resource (like an axis or vector space) to an existing buffer, without affecting the size of the buffer or the data contained in the buffer. The following examples illustrate the use of this technique:
  • A single resource (e.g. axis or vector space) can use buffer 1 for a contouring operation, and then be switched over to buffer 2 for a subsequent operation. You can set up the two buffers ahead of time. When the first operation is complete, you can make an additional call to this function with a bufferSize of 0, the same value for resource, and the new buffer number for buffer.
  • If you want to reuse a buffer with another resource, call this function with the same buffer number, a bufferSize of 0, and a new value for resource. Both resources can still use the single buffer, but not at the same time.
    
    A buffer size of 0 allows you to associate a resource with an existing buffer, without changing the contents of the existing buffer. Also, a buffer size of 0 can be used to leave the current buffer alone, but change the value of another parameter, such as totalPoints. If you are reconfiguring a buffer with a bufferSize of 0, the read mark is set to 0. If the buffer is an output buffer, the write mark is set to bufferSize. If the buffer is an input buffer, the write mark is set to 0.
  • After a contouring operation, the same buffer of points can be contoured again, with a different time interval between points, or number of totalPoints. Pass in a 0 for buffer size and change the other parameters as appropriate.
• When reconfiguring an existing output buffer (e.g. contouring buffer) by passing a bufferSize of 0, the buffer is assumed to be full of data. If you want to change its contents, do so before reconfiguring the buffer.
• When a buffer has been saved to ROM using the Object Memory Management function, and the association between the buffer and the resource (for example, axis or vector space) has been lost (most likely through a power cycle or a call to Clear Buffer), the association between the resource and the buffer needs to be re-established before a buffered operation can be performed with the buffer. Because the buffer already exists in ROM, specifying a bufferSize of 0 causes the NI motion controller to associate the specified resource with the specified buffer without allocating any new memory for the buffer. If the buffer does not exist, an NIMC_objectReferenceError is generated.
• The maximum buffer size is 16,364 data points on a 7340 and 7350 controller. Besides the data stored in each buffer, some space is used internally for bookkeeping and state information. Refer to Buffered Operations for information about the total amount RAM and ROM on each controller.
• When a buffer is configured, memory for the buffer is allocated in the controller's onboard RAM. The buffer persists until the buffer is cleared with the Clear Buffer function, or the controller is reset, usually through a power cycle. You can save the buffer to ROM with the Object Memory Management function for later use, even after the power has been cycled. When using a buffer stored in ROM, you cannot write to the buffer.
• The NIMC_HIGH-SPEED_CAPTURE_READBACK attribute is not supported for 7340 controllers.
• The NIMC_CAMMING_POSITION attribute is not supported for 73xx controllers.

• For the NIMC_POSITION_DATA attribute, use the following equation to calculate the actual interval, rounded to the next microsecond:

  

  where r = requestedInterval in milliseconds (ms)
  a = actual interval in milliseconds (ms)
  p = PID rate in microseconds (µs)

  For example, given a PID rate of 250 µs, a time interval of 11.2 ms between points is physically impossible, but a requestedInterval of 11.25 ms can be accomplished. So a call to Configure Buffer with interval set to 11.2 configures the buffer for 11.25 ms, because that is the shortest possible interval that is greater than or equal to the requested interval. The actual value being used, 11.25 in this case, is returned as an output parameter. The following table shows the minimum and maximum intervals for all valid PID rates.

  PID rate	Minimum Interval	Maximum Interval
  62.5 µs	10.0 ms	11.3125 ms
  125 µs	10.0 ms	22.625 ms
  187.5 µs	10.125 ms	33.9375 ms
  250 µs	10.0 ms	45.25 ms
  312.5 µs	10.0 ms	56.5625 ms
  375 µs	10.125 ms	67.875 ms
  437.5 µs	10.0625 ms	79.1875 ms
  500 µs	10.0 ms	90.5 ms

• You can change the PID rate in MAX or with the Enable Axis function.

NI SoftMotion Controller Considerations

The following list includes considerations you must make when you are using this function with the NI SoftMotion Controller:

• The NI SoftMotion Controller supports only the NIMC_POSITION_DATA and NIMC_CAMMING_POSITION attributes.
• The NI SoftMotion Controller for Copley Controls' CANopen devices supports minimum contour intervals as follows:
  • 10 ms for a motion control system that uses 1 to 8 axes
  • 20 ms for a motion control system that uses 9 to 15 axes
  • 30 ms for a motion control system that uses 16 to 23 axes
  • 40 ms for a motion control system that uses 24 to 30 axes

• If you set oldDataStop to false and totalPoints is greater than bufferSize, you must set totalPoints to a multiple of bufferSize. Otherwise, an error is returned.
  
  For example, to repeat a contour of 2,000 points 100 times, set oldDataStop to false, totalPoints to 200,000, and bufferSize to 2,000.

• The size of the buffer is limited by the system resources.