Fn

The Fn object gives you access to a number of handy utility functions and "constants" for your Johnny-Five convenience. The source in lib/fn.js has extensive inline comments, as well. The Fn object is available in Johnny-Five's top-level context:

var five = require('johnny-five');
var total = five.Fn.sum([3, 4, 2, 0, 5]); // -> 14

API

General Utility Functions

• constrain(value, lower, upper) Constrain value so that it falls within the range bounded by lower and upper.

  five.Fn.constrain(235, 0, 255); // --> 235
  five.Fn.constrain(948, 0, 255); // --> 255

• inRange(value, lower, upper) Is the value within the range bounded by lower and upper?

  five.Fn.inRange(235, 0, 255); // --> true
  five.Fn.inRange(948, 0, 255); // --> false

• map(value, fromLow, fromHigh, toLow, toHigh) Map a numeric value from one range to another. Based on Arduino's map(...).

  five.Fn.map(500, 0, 1000, 0, 255); // --> 127

• fmap(...) Like Fn.map, but the return value will be cast to a Float32.

• range(lower, upper, tick) Generate an Array of Numbers with element values ranging from lower to upper; the step (increment/decrement) between each is defined by tick. If range is invoked with a single argument, it will be used to determine the number of elements in the resulting Array.

  five.Fn.range(5); // -> [0, 1, 2, 3, 4];
  five.Fn.range(5, 10); // -> [5, 6, 7, 8, 9, 10];
  five.Fn.range(3, 27, 3); // -> [3, 6, 9, 12, 15, 18, 21, 24, 27];
  five.Fn.range(0, -9, -3); // -> [0, -3, -6, -9];

• range.prefixed(prefix, ...) Adds prefix to each element in the range Array returned by Fn.range. The function passes on arguments (other than prefix) to the range function.

  five.Fn.range.prefixed("A", 0, 10, 2); // -> ["A0", "A2", "A4", "A6", "A8", "A10"]

• scale(...) Alias for Fn.map

• fscale(...) Alias for Fn.fmap

• sum(values) Calculate a sum of all the elements in an Array.

  five.Fn.sum([3, 4, 2, 0, 5]); // -> 14

• toFixed(number, digits) Format a number such that it has a given number of digits after the decimal point.

  five.Fn.toFixed(5.4564, 2); // -> 5.46
  five.Fn.toFixed(1.5, 2); // -> 1.5

• uid() Generate a reasonably-unique ID string.

Functions for Manipulating Bits and Integers

• bitSize(n) Return the number of bits in a given number n.

  five.Fn.bitSize(1000); // --> 10

• bitValue(bit) (also aliased as _BV and bv) Return a value with the bit at the position (bit) indicated set (to 1). (From avr/io.h "BV")

  An example: logically OR these bits together:
  var ORed = _BV(0) | _BV(2) | _BV(7);
  
  BIT         7  6  5  4  3  2  1  0
  ---------------------------------------------------------
  _BV(0)  =   0  0  0  0  0  0  0  1
  _BV(2)  =   0  0  0  0  0  1  0  0
  _BV(7)  =   1  0  0  0  0  0  0  0
  ORed    =   1  0  0  0  0  1  0  1
  
  ORed === 133;
  

Ints from Multiple Bytes

The following functions allow you to build 16-, 24- and 32-bit numbers by cobbling together multiple bytes:

• int16(msb, lsb) Combine msb (most-significant byte) and lsb (least-significant byte) into a 16-bit signed integer.

  five.Fn.int16(8, 0); // --> 2048
  five.Fn.int16(255, 255); // --> -1 (because signed)

• uint16(msb, lsb) Combine msb (most-significant byte) and lsb (least-significant byte) into a 16-bit unsigned integer.

  five.Fn.int16(8, 0); // --> 2048
  five.Fn.int16(255, 255); // --> 65535 (because unsigned)

• int24(b16, b8, b0) Combine three bytes to make a signed 24-bit integer.

  five.Fn.int24(127, 255, 255); // --> 8388607
  five.Fn.int24(255, 255, 255); // --> -1 (because signed)

• uint24(b16, b8, b0) Combine three bytes to make an unsigned 24-bit integer.

  five.Fn.int24(127, 255, 255); // --> 8388607
  five.Fn.int24(255, 255, 255); // --> 16777215 (because unsigned)

• int32(b24, b16, b8, b0) Combine four bytes to make a signed 32-bit integer.

  five.Fn.int32(127, 255, 255, 255); // --> 2147483647
  five.Fn.int32(200, 255, 255, 255); // --> -922746881 (because signed)

• uint32(b24, b16, b8, b0) Combine three bytes to make an unsigned 32-bit integer.

  five.Fn.uint32(127, 255, 255, 255); // --> 2147483647
  five.Fn.uint32(200, 255, 255, 255); // --> 4294967295 (because unsigned)

Auto-Generated Functions

The following functions are available in the bitSizes of: 4, 8, 10, 12, 16, 20, 24, 32

• u[bitSize](value) (e.g. Fn.u8) Constrain value to the valid range of unsigned ints for the given bitsize.

  Fn.u8(255); // --> 255
  Fn.u8(256); // --> 255
  Fn.u8(0);   // --> 0
  Fn.u4(255); // --> 15

• s[bitSize](value) (e.g. Fn.s16) Constrain value to the valid range of signed ints for the given bitsize.

  Fn.s8(255); // --> -1
  Fn.s8(127); // --> 127
  Fn.s8(128); // --> -128

Useful "Constants"

• RAD_TO_DEG
• DEG_TO_RAD
• TAU
• POW_2_0 through POW_2_53 Powers of 2