Running Mac OS X's built-in DHCP server

April 10, 2011 | Mac OS X

It turns out that Mac OS X comes with a DHCP server built-in. There don't seem to be any good and simple instructions out there on how to use it. Or at least, there weren't any.... until now!

The server is called bootpd and does both DHCP and BOOTP. These instructions just describe using it for DHCP, however.

To start, you need to create a configuration file for the server. The file should be stored in /etc/bootpd.plist. Here's a sample configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>bootp_enabled</key>
<false/>
<key>detect_other_dhcp_server</key>
<integer>1</integer>
<key>dhcp_enabled</key>
<array>
<string>en0</string>
</array>
<key>reply_threshold_seconds</key>
<integer>0</integer>
<key>Subnets</key>
<array>
<dict>
<key>allocate</key>
<true/>
<key>lease_max</key>
<integer>86400</integer>
<key>lease_min</key>
<integer>86400</integer>
<key>name</key>
<string>192.168.33</string>
<key>net_address</key>
<string>192.168.33.0</string>
<key>net_mask</key>
<string>255.255.255.0</string>
<key>net_range</key>
<array>
<string>192.168.33.2</string>
<string>192.168.33.254</string>
</array>
</dict>
</array>
</dict>
</plist>

This file sets up the DHCP server to run on the interface named en0, which is typically the (non-wireless) Ethernet port. It assumes that that port has been configured with the IP address 192.168.33.1, and dishes out addresses from 192.168.33.2 to 192.168.33.254.

To get more information on editing this file, take a look at the bootpd manfile:

man bootpd

To start the server, run the following command:

sudo /bin/launchctl load -w /System/Library/LaunchDaemons/bootps.plist

Stopping the server is very similar:

sudo /bin/launchctl unload -w /System/Library/LaunchDaemons/bootps.plist

If you want to create static assignments, so that a given device always has the same IP address, you need to create a file called /etc/bootptab. There's a small sample of the file below. For more information, just do man bootptab

%%
# machine entries have the following format:
#
# hostname hwtype hwaddr ipaddr bootfile
client1 1 00:01:02:03:04:05 10.0.0.20
client2 1 00:a0:b2:ef:ff:0a 10.0.0.20

Make sure to include the %% at the top of the file. It's safe to leave the bootfile field empty because we're just using bootpd as a DHCP server, not a bootp server.

In Defense of the C99 Boolean Type

April 9, 2011 | Embedded Software

I really like a lot of the features in C99, including the new bool type. A lot of people have dismissed it as syntactic sugar or language bloat, but it does bring something new to the table.

First, how do you use bool? The best way is to include the stdbool.h header, which defines the bool type and the constants true and false as follows:

#define bool    _Bool
#define true 1
#define false 0

To maintain compatibility, the actual new keyword added to the language was _Bool. stdbool.h then defines a macro that allows you to use the slightly friendlier bool type. That way code that defines its own, incompatible bool type can continue to work by just not including stdbool.h.

So far, there's nothing special here. The real excitement is buried in the ISO C99 standard. Here's section 6.3.1.2 of the n1256 ISO committee draft (yes, I'm too cheap to shell out $40 for the offical version of the standard).

When any scalar value is converted to _Bool, the result is 0 if the value compares equal to 0; otherwise, the result is 1

Exciting, isn't it? Before the days of C99, programmers would typically represent boolean values as an int. That would cause all kinds of problems such as:

if( somevalue == TRUE )
{
/* do something */
}

This would cause unexpected behavior because TRUE would typically be defined to be 1, but somevalue wasn't guaranteed to just be 0 or 1. Now, if somevalue is a C99 bool, there is that guarantee. Of course, the code above is still dumb because it's excessively verbose.

Another problem was packing "boolean" values into flags. To get around the problem of "booleans" not being limited to 0 and 1, you would end up writing code like

flags = (condition1 ? 1 : 0 ) << 1 | (condition2 ? 1 : 0 ) << 2 | (condition3 ? 1 : 0 ) << 3;

Now, if the three condition variables above all have type bool, you can make this much more compact:

flags = (condition1 << 1) | (condition2 << 2) | (condition3  << 3);

So, does this actually work? Let's give it a whirl! Here's a silly little test function.

#include <stdio.h>
#include <stdbool.h>

bool test( void )
{
return printf( "blah" );
}

Here's the disassembly of that function (compiled for ARM, because I hate reading x86 assembly language). Notice addresses 10 and 14. Address 10 subtracts 0 from r0 and stores the result in r0 (on ARM r0 holds the return value from a function, which is printf in this case). That's setting up a comparison to 0 for address 14, which sets r0 to 1 if the return value from printf was not zero. If the return value from printf was 0, then r0 already has 0 in it, so there's nothing to do (clever optimizer!). Of course, r0 then becomes the return value from the test function, so this does exactly what we expect: It returns 0 if printf returned a value of 0, and 1 otherwise.

 0:   e52de004    push    {lr}        ; (str lr, [sp, #-4]!)
4: e59f0018 ldr r0, [pc, #24] ; 24 <test+0x24>
8: e24dd004 sub sp, sp, #4 ; 0x4
c: ebfffffe bl 0 <printf>
10: e2500000 subs r0, r0, #0 ; 0x0
14: 13a00001 movne r0, #1 ; 0x1
18: e28dd004 add sp, sp, #4 ; 0x4
1c: e49de004 pop {lr} ; (ldr lr, [sp], #4)
20: e12fff1e bx lr

And there you have it. The bool type isn't the most ground-breaking feature in C, but it isn't completely useless either.

Consistent Overhead Byte Stuffing

March 26, 2011 | Embedded Software

Framing packets transmitted on a UART serial link (such as RS-232 or RS-485) is a common problem in embedded programming. The typical approach is to put framing characters at the beginning and end of the packet. If a framing character occurs in the packet, it is escaped using a technique called byte stuffing. This sucks for a few reasons, but there's a better way. The recently developed algorithm called Consistent Overhead Byte Stuffing is a great solution that should be in every embedded software engineer's toolbox.

First, a bit of background. I'm working on a project where I have to transmit data between two microcontrollers using RS-422. RS-422 is a differential signalling standard that is often used in place of RS-232 to connect two UARTs when electrical isolation and/or noise immunity are required.

The question came up, how do we assemble packets on the transmitter and detect packet boundaries on he receiver? Our packets all have the same size and can contain arbitrary binary data. My first thought was to use idle line detection. If our UART detects enough bit times without a start bit, it can give us an idle line interrupt. Because we're feeding the transmitting UART with DMA, we can guarantee that there are no gaps in the middle of the packet that would cause a false idle line to be detected.

My boss pointed out that I was relying on an implementation detail that might not be valid if we ever moved to a really cheap microcontroller. He encouraged me to come up with a solution that put the framing into the packet itself.

The traditional way to do this is with byte stuffing. You designate a character (such as STX, ASCII 0x02) as the start of frame character and another (often ETX, ASCII 0x03) as the end of frame character. If there's a possibility that ETX or STX will occur in your data, you designate a third character as the escape character (ESC, ASCII 0x1F, for example). STX, ETX, and ESC characters in the data are replaced by an ESC followed by mangled version of he character (the character XORed with 0x20 is a popular choice).

There are two problems with this system:

  • It can add a lot of overhead. In the worst case, the encoded data could be twice the size of the original data. Unless you can be sure this won't happen, you have to design your buffers and bandwidth to handle this worst case.

  • The amount of overhead is variable. If you want to use DMA or FIFO buffers to send and receive your data, dealing with variable length data can be annoying. For example, you can't reliably request an interrupt after a frame's worth of data has been received. When you're transmitting at multiple megabits per second, you really don't want to check for a complete frame after each character is received.

Returning to the story above, I was really annoyed. My boss had a good point, but byte stuffing is just a pain. I did a bunch of googling, and finally came across COBS. It has the following great properties:

  • It removes all zero bytes from the original message, allowing the zero byte to be used as a frame delimiter.

  • The worst-case overhead is just 1 byte for every 254 bytes of data, or 0.39%.

  • For messages smaller than 254 bytes, the overhead is constant (exactly 1 byte).

  • The encoding process is fairly efficient (no complicated rearranging of input data across multiple bytes).

There's sample code on the Wikipedia COBS page. I've improved the Wikipedia code in a few ways:

  • My encoder and decoder return the length of the output data, because that size varies depending on the input data.

  • My decoder checks the validity of its input data to protect against corrupted or malicious data. The original Wikipedia code would cause a buffer overflow if an overly high block length code occurred at the end of the input data.

  • My decoder doesn't put the imaginary zero byte at the end of its output.

  • My encoder and decoder use modern C99. For example, specifying the restrict qualifier on the input and output pointers means the code can be more heavily optimized (restrict is a promise that the two buffers do not overlap, which helps the optimizer eliminate unneeded loads and stores).

COBS resources:

Here's my C implementation of COBS:

/* Copyright 2011, Jacques Fortier. All rights reserved.
*
* Redistribution and use in source and binary forms are permitted, with or without modification.
*/
#include <stdint.h>
#include <stddef.h>

/* Stuffs "length" bytes of data at the location pointed to by
* "input", writing the output to the location pointed to by
* "output". Returns the number of bytes written to "output".
*
* Remove the "restrict" qualifiers if compiling with a
* pre-C99 C dialect.
*/
size_t cobs_encode(const uint8_t * restrict input, size_t length, uint8_t * restrict output)
{
size_t read_index = 0;
size_t write_index = 1;
size_t code_index = 0;
uint8_t code = 1;

while(read_index < length)
{
if(input[read_index] == 0)
{
output[code_index] = code;
code = 1;
code_index = write_index++;
read_index++;
}
else
{
output[write_index++] = input[read_index++];
code++;
if(code == 0xFF)
{
output[code_index] = code;
code = 1;
code_index = write_index++;
}
}
}

output[code_index] = code;

return write_index;
}

/* Unstuffs "length" bytes of data at the location pointed to by
* "input", writing the output * to the location pointed to by
* "output". Returns the number of bytes written to "output" if
* "input" was successfully unstuffed, and 0 if there was an
* error unstuffing "input".
*
* Remove the "restrict" qualifiers if compiling with a
* pre-C99 C dialect.
*/
size_t cobs_decode(const uint8_t * restrict input, size_t length, uint8_t * restrict output)
{
size_t read_index = 0;
size_t write_index = 0;
uint8_t code;
uint8_t i;

while(read_index < length)
{
code = input[read_index];

if(read_index + code > length && code != 1)
{
return 0;
}

read_index++;

for(i = 1; i < code; i++)
{
output[write_index++] = input[read_index++];
}
if(code != 0xFF && read_index != length)
{
output[write_index++] = '\0';
}
}

return write_index;
}

Creating Excerpts in Jekyll with Wordpress-style <!--more--> HTML Comments

March 6, 2011 | Web Development

I just finished converting my blog to Jekyll. If you've never heard of Jekyll, it's a static blog publishing tool. Unlike Wordpress, where the HTML for your blog is generated on-the-fly by your server every time someone accesses your site, Jekyll is meant to run on your PC. You write your posts in a simple text format (often Markdown), run Jekyll on them, and then upload the posts to your server. The nice thing is that your server dosn't need any PHP or Python or Ruby or anything. And, if your website gets a ton of traffic, there's no database to crash. In fact, since you don't need any scripting languages or a database, you can just throw everything on Amazon S3 and be guaranteed that your site will never crash.

The downside of Jekyll is that its features are kind of minimalistic. That minimalism is nice because it means there's less to learn. That minimalism also results in lots of blog posts on the theme of "I switched to Jekyll and it's awesome now that I've hacked it up to implement this Wordpress feature I couldn't live without." On that note, here's how you can put a list of post excerpts on your Jekyll blog's front page and archive pages, with the "fold" marked with a <!--more--> HTML comment just like in Wordpress.

There are lots of pages out there showing how to do similar things by forking Jekyll. But, with the newish Jekyll plugin system, there's no need to mess with the Jekyll core. Instead, just add a plugin that adds a new Liquid filter. Here's postmore.rb, which should go in the _plugins directory in the root of your Jekyll site:

module PostMore
  def postmorefilter(input, url, text)
    if input.include? "<!--more-->"
      input.split("<!--more-->").first + "<p class='more'><a href='#{url}'>#{text}</a></p>"
    else
      input
    end
  end
end

Liquid::Template.register_filter(PostMore)

This creates and registers a filter called postmorefilter. It takes two arguments: the URL of the main post body page, and the text to use on the link to the page. To use it, you just apply it to the post's contents. If the post containes the <!--more--> fold marker, then the text up to the marker will be output, followed by a link to the page with the full post. If there is no marker, then the entire post is output without a link. For example:

{{ page.content | postmorefilter: page.url, "Read the rest of this entry" }}

The next step is to modify your index.html to output your posts. I wanted to put the most recent few posts on my blog's front page, and then have archive pages with older posts. To do that, I had to turn on Jekyll's pagination feature by setting paginate: 6 in my _config.yml (where 6 is the number of posts per page). Then, I had to modify my index.html to use the paginator. Note that if you want to do this in another file, you need to set the paginate_file setting in your _config.yml. Here's what my index.html looks like:

---
layout: twocolumn
title: Jacques Fortier
---

<div id="home">
  <!-- iterate through the posts on this page -->
  {% for page in paginator.posts %}
    <div class="post">
      <h1><a href="{{ page.url }}">{{ page.title }}</a></h1>
      <p class="meta">{{ page.date | date: "%B %e, %Y" }}</p>
        {{ page.content | postmorefilter: page.url, "Read the rest of this entry" }}
    </div>
  {% endfor %}

  <!-- links to prev and next pages for browsing thru archives -->
  {% if paginator.previous_page == 1 %}
    <span id="newer"><a href="/">&laquo;&laquo; Newer Entries</a></span>
  {% elsif paginator.previous_page %}
    <span id="newer"><a href="/page{{ paginator.previous_page }}">&laquo;&laquo; Newer Entries</a></span>
  {% endif %}
  {% if paginator.next_page %}
    <span id="older"><a href="/page{{ paginator.next_page }}">Older Entries &raquo;&raquo;</a></span>
  {% endif %}

</div>

Of course, you would set the title and layout in the YAML front-matter to whatever you're using on your blog.

To summarize:

Adding Titles to iPad UIToolbars

January 9, 2011 | iOS Software

I recently had to figure out how to add a title to a UIToolbar at the top of an iPad view. The toolbar was in the “silver” style and the idea was to make the title look like the titles used in navigation controllers. If I just had one button on each side of the title, I could have used a navigation bar. In this case, I needed to have a bunch of buttons in the toolbar, so a UINavigationBar couldn’t work.

The concept is pretty simple: just add a UIBarButtonItem with a label as the custom view. The trickier part is getting everything matched up, pixel-perfect, with the stock controls. After a bunch of fiddling around with xScope, here’s what I came with.

Start by creating a label that’s 23 pixels tall, and wide enough to hold your text. Set its font to boldSystemFontOfSize:20 and set the text alignment to UITextAlignmentCentered.

Figuring out the colors was a bit tricky. For an iPad silver-style toolbar (UIBarStyleDefault with no tintColor applied), fiddling around with xScope gave me a text color in HTML #RRGGBB format of #717880 (just divide those values by 255.0 to get the color components expected by UIColor). The shadow color is #e6e7eb. The shadowOffset should be (0, 1), which puts the shadow 1 pixel above the text.

The last detail was getting the label to line up vertically as expected. If you just put the label directly in a UIBarButtonItem it’s close. In fact, it’s just one pixel lower than the title in UINavigationBar. To make it match up perfectly, I ended up putting the label into a container UIView that’s one pixel taller than the label.

And that’s all there is to it. I’ve put this code into a category of UILabel (freely licensed under the WTFPL). You can use the category like this:

UIBarButtonItem *title = [[UIBarButtonItem alloc] initWithTitle:@"Title" width:120];
// Grab the label if you want to change the title later on
UILabel *titleLabel = [title.customView.subviews lastObject];

The code is below, or you can grab it from GitHub: UIBarButtonItem to add title to UIToolbar on iPad

//  UIBarButtonItem+JFAdditions.m
//
// Created by Jacques Fortier on 1/10/11.
// Copyright 2011 Jacques Fortier.
// Released under the WTFPL (see LICENSE or http://sam.zoy.org/wtfpl/COPYING)

@interface UIBarButtonItem(JFAdditions)

- (id)initWithTitle:(NSString *)title width:(CGFloat)width;

@end

@implementation UIBarButtonItem(JFAdditions)

- (id)initWithTitle:(NSString *)title width:(CGFloat)width {
UILabel *label = [[UILabel alloc] initWithFrame:CGRectMake(0, 0, width, 23)];
label.text = title;
label.backgroundColor = [UIColor clearColor];
label.opaque = NO;
label.textColor = [UIColor colorWithRed:0x71/255.0 green:0x78/255.0 blue:0x80/255.0 alpha:1.0];
label.shadowOffset = CGSizeMake(0, 1);
label.shadowColor = [UIColor colorWithRed:0xe6/255.0 green:0xe7/255.0 blue:0xeb/255.0 alpha:1.0];
label.textAlignment = UITextAlignmentCenter;
label.font = [UIFont boldSystemFontOfSize:20.0];
UIView *labelContainer = [[UIView alloc] initWithFrame:CGRectMake(0, 0, width, 24)];
[labelContainer addSubview:label];

self = [self initWithCustomView:labelContainer];

[label release];
[labelContainer release];

return self;
}

@end