MicroBitConfig.h

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 /**
00027   * Compile time configuration options for the micro:bit runtime.
00028   */
00029 
00030 #ifndef MICROBIT_CONFIG_H
00031 #define MICROBIT_CONFIG_H
00032 
00033 #include "mbed.h"
00034 #include "yotta_cfg_mappings.h"
00035 
00036 //
00037 // Memory configuration
00038 //
00039 
00040 // The start address of usable RAM memory.
00041 #ifndef MICROBIT_SRAM_BASE
00042 #define MICROBIT_SRAM_BASE                      0x20000008
00043 #endif
00044 
00045 // Physical address of the top of SRAM.
00046 #ifndef MICROBIT_SRAM_END
00047 #define MICROBIT_SRAM_END                       0x20004000
00048 #endif
00049 
00050 // The end address of memory normally reserved for Soft Device.
00051 #ifndef MICROBIT_SD_LIMIT
00052 #define MICROBIT_SD_LIMIT                       0x20002000
00053 #endif
00054 
00055 // The physical address in memory of the Soft Device GATT table.
00056 #ifndef MICROBIT_SD_GATT_TABLE_START
00057 #define MICROBIT_SD_GATT_TABLE_START            0x20001900
00058 #endif
00059 
00060 // Physical address of the top of the system stack (on mbed-classic this is the top of SRAM)
00061 #ifndef CORTEX_M0_STACK_BASE
00062 #define CORTEX_M0_STACK_BASE                    MICROBIT_SRAM_END
00063 #endif
00064 
00065 // Amount of memory reserved for the stack at the end of memory (bytes).
00066 #ifndef MICROBIT_STACK_SIZE
00067 #define MICROBIT_STACK_SIZE                     2048
00068 #endif
00069 
00070 // Physical address of the end of mbed heap space.
00071 #ifndef MICROBIT_HEAP_END
00072 #define MICROBIT_HEAP_END                       (CORTEX_M0_STACK_BASE - MICROBIT_STACK_SIZE)
00073 #endif
00074 
00075 // Enables or disables the MicroBitHeapllocator. Note that if disabled, no reuse of the SRAM normally
00076 // reserved for SoftDevice is possible, and out of memory condition will no longer be trapped...
00077 // i.e. panic() will no longer be triggered on memory full conditions.
00078 #ifndef MICROBIT_HEAP_ALLOCATOR
00079 #define MICROBIT_HEAP_ALLOCATOR                 1
00080 #endif
00081 
00082 // Block size used by the allocator in bytes.
00083 // n.b. Currently only 32 bits (4 bytes) is supported.
00084 #ifndef MICROBIT_HEAP_BLOCK_SIZE
00085 #define MICROBIT_HEAP_BLOCK_SIZE                4
00086 #endif
00087 
00088 // The proportion of SRAM available on the mbed heap to reserve for the micro:bit heap.
00089 #ifndef MICROBIT_NESTED_HEAP_SIZE
00090 #define MICROBIT_NESTED_HEAP_SIZE               0.75
00091 #endif
00092 
00093 // If defined, reuse any unused SRAM normally reserved for SoftDevice (Nordic's memory resident BLE stack) as heap memory.
00094 // The amount of memory reused depends upon whether or not BLE is enabled using MICROBIT_BLE_ENABLED.
00095 // Set '1' to enable.
00096 #ifndef MICROBIT_HEAP_REUSE_SD
00097 #define MICROBIT_HEAP_REUSE_SD                  1
00098 #endif
00099 
00100 // The amount of memory allocated to Soft Device to hold its BLE GATT table.
00101 // For standard S110 builds, this should be word aligned and in the range 0x300 - 0x700.
00102 // Any unused memory will be automatically reclaimed as HEAP memory if both MICROBIT_HEAP_REUSE_SD and MICROBIT_HEAP_ALLOCATOR are enabled.
00103 #ifndef MICROBIT_SD_GATT_TABLE_SIZE
00104 #define MICROBIT_SD_GATT_TABLE_SIZE             0x300
00105 #endif
00106 
00107 //
00108 // Fiber scheduler configuration
00109 //
00110 
00111 // Scheduling quantum (milliseconds)
00112 // Also used to drive the micro:bit runtime system ticker.
00113 #ifndef SYSTEM_TICK_PERIOD_MS
00114 #define SYSTEM_TICK_PERIOD_MS                   6
00115 #endif
00116 
00117 //
00118 // Message Bus:
00119 // Default behaviour for event handlers, if not specified in the listen() call
00120 //
00121 // Permissable values are:
00122 //   MESSAGE_BUS_LISTENER_REENTRANT
00123 //   MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY
00124 //   MESSAGE_BUS_LISTENER_DROP_IF_BUSY
00125 //   MESSAGE_BUS_LISTENER_IMMEDIATE
00126 
00127 #ifndef EVENT_LISTENER_DEFAULT_FLAGS
00128 #define EVENT_LISTENER_DEFAULT_FLAGS            MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY
00129 #endif
00130 
00131 //
00132 // Maximum event queue depth. If a queue exceeds this depth, further events will be dropped.
00133 // Used to prevent message queues growing uncontrollably due to badly behaved user code and causing panic conditions.
00134 //
00135 #ifndef MESSAGE_BUS_LISTENER_MAX_QUEUE_DEPTH
00136 #define MESSAGE_BUS_LISTENER_MAX_QUEUE_DEPTH    10
00137 #endif
00138 
00139 //
00140 // Core micro:bit services
00141 //
00142 
00143 // To reduce memory cost and complexity, the micro:bit allows components to register for
00144 // periodic callback events during interrupt context, which occur every scheduling quantum (FIBER_TICK_PERIOD_MS)
00145 // This defines the maximum size of interrupt callback list.
00146 #ifndef MICROBIT_SYSTEM_COMPONENTS
00147 #define MICROBIT_SYSTEM_COMPONENTS              10
00148 #endif
00149 
00150 // To reduce memory cost and complexity, the micro:bit allows components to register for
00151 // periodic callback events when the processor is idle.
00152 // This defines the maximum size of the idle callback list.
00153 #ifndef MICROBIT_IDLE_COMPONENTS
00154 #define MICROBIT_IDLE_COMPONENTS                6
00155 #endif
00156 
00157 //
00158 // BLE options
00159 //
00160 // The BLE stack is very memory hungry. Each service can therefore be compiled in or out
00161 // by enabling/disabling the options below.
00162 //
00163 // n.b. The minimum set of services to enable over the air programming of the device will
00164 // still be brought up in pairing mode regardless of the settings below.
00165 //
00166 
00167 // Enable/Disable BLE during normal operation.
00168 // Set '1' to enable.
00169 #ifndef MICROBIT_BLE_ENABLED
00170 #define MICROBIT_BLE_ENABLED                    1
00171 #endif
00172 
00173 // Enable/Disable BLE pairing mode mode at power up.
00174 // Set '1' to enable.
00175 #ifndef MICROBIT_BLE_PAIRING_MODE
00176 #define MICROBIT_BLE_PAIRING_MODE               1
00177 #endif
00178 
00179 // Enable/Disable the use of private resolvable addresses.
00180 // Set '1' to enable.
00181 // n.b. This is known to be a feature that suffers compatibility issues with many BLE central devices.
00182 #ifndef MICROBIT_BLE_PRIVATE_ADDRESSES
00183 #define MICROBIT_BLE_PRIVATE_ADDRESSES          0
00184 #endif
00185 
00186 // Convenience option to enable / disable BLE security entirely
00187 // Open BLE links are not secure, but commonly used during the development of BLE services
00188 // Set '1' to disable all secuity
00189 #ifndef MICROBIT_BLE_OPEN
00190 #define MICROBIT_BLE_OPEN                       0
00191 #endif
00192 
00193 // Configure for open BLE operation if so configured
00194 #if (MICROBIT_BLE_OPEN == 1)
00195 #define MICROBIT_BLE_SECURITY_LEVEL             SECURITY_MODE_ENCRYPTION_OPEN_LINK
00196 #define MICROBIT_BLE_WHITELIST                  0
00197 #define MICROBIT_BLE_ADVERTISING_TIMEOUT        0
00198 #define MICROBIT_BLE_DEFAULT_TX_POWER           6
00199 #endif
00200 
00201 
00202 // Define the default, global BLE security requirements for MicroBit BLE services
00203 // May be one of the following options (see mbed's SecurityManager class implementaiton detail)
00204 // SECURITY_MODE_ENCRYPTION_OPEN_LINK:      No bonding, encryption, or whitelisting required.
00205 // SECURITY_MODE_ENCRYPTION_NO_MITM:        Bonding, encyption and whitelisting but no passkey.
00206 // SECURITY_MODE_ENCRYPTION_WITH_MITM:      Bonding, encrytion and whitelisting with passkey authentication.
00207 //
00208 #ifndef MICROBIT_BLE_SECURITY_LEVEL
00209 #define MICROBIT_BLE_SECURITY_LEVEL             SECURITY_MODE_ENCRYPTION_WITH_MITM
00210 #endif
00211 
00212 // Enable/Disable the use of BLE whitelisting.
00213 // If enabled, the micro:bit will only respond to connection requests from
00214 // known, bonded devices.
00215 #ifndef MICROBIT_BLE_WHITELIST
00216 #define MICROBIT_BLE_WHITELIST                  1
00217 #endif
00218 
00219 // Define the period of time for which the BLE stack will advertise (seconds)
00220 // Afer this period, advertising will cease. Set to '0' for no timeout (always advertise).
00221 #ifndef MICROBIT_BLE_ADVERTISING_TIMEOUT
00222 #define MICROBIT_BLE_ADVERTISING_TIMEOUT        0
00223 #endif
00224 
00225 // Defines default power level of the BLE radio transmitter.
00226 // Valid values are in the range 0..7 inclusive, with 0 being the lowest power and 7 the highest power.
00227 // Based on trials undertaken by the BBC, the radio is normally set to its lowest power level
00228 // to best protect children's privacy.
00229 #ifndef MICROBIT_BLE_DEFAULT_TX_POWER
00230 #define MICROBIT_BLE_DEFAULT_TX_POWER           0
00231 #endif
00232 
00233 // Enable/Disable BLE Service: MicroBitDFU
00234 // This allows over the air programming during normal operation.
00235 // Set '1' to enable.
00236 #ifndef MICROBIT_BLE_DFU_SERVICE
00237 #define MICROBIT_BLE_DFU_SERVICE                1
00238 #endif
00239 
00240 // Enable/Disable BLE Service: MicroBitEventService
00241 // This allows routing of events from the micro:bit message bus over BLE.
00242 // Set '1' to enable.
00243 #ifndef MICROBIT_BLE_EVENT_SERVICE
00244 #define MICROBIT_BLE_EVENT_SERVICE              1
00245 #endif
00246 
00247 // Enable/Disable BLE Service: MicroBitDeviceInformationService
00248 // This enables the standard BLE device information service.
00249 // Set '1' to enable.
00250 #ifndef MICROBIT_BLE_DEVICE_INFORMATION_SERVICE
00251 #define MICROBIT_BLE_DEVICE_INFORMATION_SERVICE 1
00252 #endif
00253 
00254 //
00255 // Accelerometer options
00256 //
00257 
00258 // Enable this to read 10 bits of data from the acclerometer.
00259 // Otherwise, 8 bits are used.
00260 // Set '1' to enable.
00261 #ifndef USE_ACCEL_LSB
00262 #define USE_ACCEL_LSB                           0
00263 #endif
00264 
00265 //
00266 // Display options
00267 //
00268 
00269 // Selects the matrix configuration for the display driver.
00270 // Known, acceptable options are:
00271 //
00272 #define MICROBUG_REFERENCE_DEVICE               1
00273 #define MICROBIT_3X9                            2
00274 #define MICROBIT_SB1                            3
00275 #define MICROBIT_SB2                            4
00276 
00277 #ifndef MICROBIT_DISPLAY_TYPE
00278 #define MICROBIT_DISPLAY_TYPE                   MICROBIT_SB2
00279 #endif
00280 
00281 // Selects the minimum permissable brightness level for the device
00282 // in the region of 0 (off) to 255 (full brightness)
00283 #ifndef MICROBIT_DISPLAY_MINIMUM_BRIGHTNESS
00284 #define MICROBIT_DISPLAY_MINIMUM_BRIGHTNESS     1
00285 #endif
00286 
00287 // Selects the maximum permissable brightness level for the device
00288 // in the region of 0 (off) to 255 (full brightness)
00289 #ifndef MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS
00290 #define MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS     255
00291 #endif
00292 
00293 // Selects the default brightness for the display
00294 // in the region of zero (off) to 255 (full brightness)
00295 #ifndef MICROBIT_DISPLAY_DEFAULT_BRIGHTNESS
00296 #define MICROBIT_DISPLAY_DEFAULT_BRIGHTNESS     MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS
00297 #endif
00298 
00299 // Selects the default scroll speed for the display.
00300 // The time taken to move a single pixel (ms).
00301 #ifndef MICROBIT_DEFAULT_SCROLL_SPEED
00302 #define MICROBIT_DEFAULT_SCROLL_SPEED           120
00303 #endif
00304 
00305 // Selects the number of pixels a scroll will move in each quantum.
00306 #ifndef MICROBIT_DEFAULT_SCROLL_STRIDE
00307 #define MICROBIT_DEFAULT_SCROLL_STRIDE          -1
00308 #endif
00309 
00310 // Selects the time each character will be shown on the display during print operations.
00311 // The time each character is shown on the screen  (ms).
00312 #ifndef MICROBIT_DEFAULT_PRINT_SPEED
00313 #define MICROBIT_DEFAULT_PRINT_SPEED            400
00314 #endif
00315 
00316 //Configures the default serial mode used by serial read and send calls.
00317 #ifndef MICROBIT_DEFAULT_SERIAL_MODE
00318 #define MICROBIT_DEFAULT_SERIAL_MODE            SYNC_SLEEP
00319 #endif
00320 
00321 
00322 //
00323 // I/O Options
00324 //
00325 
00326 
00327 //
00328 // Define the default mode in which the digital input pins are configured.
00329 // valid options are PullDown, PullUp and PullNone.
00330 //
00331 #ifndef MICROBIT_DEFAULT_PULLMODE
00332 #define MICROBIT_DEFAULT_PULLMODE                PullDown
00333 #endif
00334 
00335 //
00336 // Panic options
00337 //
00338 
00339 // Enable this to invoke a panic on out of memory conditions.
00340 // Set '1' to enable.
00341 #ifndef MICROBIT_PANIC_HEAP_FULL
00342 #define MICROBIT_PANIC_HEAP_FULL                1
00343 #endif
00344 
00345 //
00346 // Debug options
00347 //
00348 
00349 // Enable this to route debug messages through the USB serial interface.
00350 // n.b. This also disables the user serial port 'uBit.serial'.
00351 // Set '1' to enable.
00352 #ifndef MICROBIT_DBG
00353 #define MICROBIT_DBG                            0
00354 #endif
00355 
00356 // Enable this to receive diagnostic messages from the heap allocator via the USB serial interface.
00357 // n.b. This requires MICROBIT_DBG to be defined.
00358 // Set '1' to enable.
00359 #ifndef MICROBIT_HEAP_DBG
00360 #define MICROBIT_HEAP_DBG                       0
00361 #endif
00362 
00363 // Versioning options.
00364 // We use semantic versioning (http://semver.org/) to identify differnet versions of the micro:bit runtime.
00365 // Where possible we use yotta (an ARM mbed build tool) to help us track versions.
00366 // if this isn't available, it can be defined manually as a configuration option.
00367 //
00368 #ifndef MICROBIT_DAL_VERSION
00369 #define MICROBIT_DAL_VERSION                    "unknown"
00370 #endif
00371 
00372 
00373 //
00374 // Helper macro used by the micro:bit runtime to determine if a boolean configuration option is set.
00375 //
00376 #define CONFIG_ENABLED(X) (X == 1)
00377 #define CONFIG_DISABLED(X) (X != 1)
00378 
00379 #if CONFIG_ENABLED(MICROBIT_HEAP_ALLOCATOR)
00380 #include "MicroBitHeapAllocator.h"
00381 #endif
00382 
00383 #if CONFIG_ENABLED(MICROBIT_DBG)
00384 extern RawSerial* SERIAL_DEBUG;
00385 #endif
00386 
00387 #endif